Docs / Integration

Connect an LLM

emisar exposes your runners and their action catalog as a Model Context Protocol server. Two ways to plug an LLM in:

  • Remote MCP (Claude.ai, ChatGPT, recent IDE clients) — paste one URL. emisar signs you in over OAuth; there is no API key or header to manage. This is the only way the cloud connectors work — their setup form has a URL field and nothing else.
  • Stdio bridge or static key (Claude Desktop, Claude Code, Cursor, Codex CLI, Gemini CLI, plain HTTP) — a tiny binary on your machine, or a raw bearer token, authenticated with an emk- API key.
1

Connect a cloud LLM (recommended)

Claude.ai and ChatGPT only let you enter a URL — no header, no token field. emisar is a full OAuth 2.1 authorization server, so the connector discovers it from that URL, registers itself automatically, and sends you through a one-time emisar sign-in. The single value to enter:

remote MCP server URL
https://emisar.dev/api/mcp/rpc

Claude (claude.ai)

  1. Open Settings → Connectors (on Pro/Max it's Customize → Connectors).
  2. Click +Add custom connector.
  3. Paste the Remote MCP server URL above into the URL field.
  4. Leave Advanced settings (OAuth Client ID / Client Secret) empty — emisar registers your client for you via Dynamic Client Registration. Click Add.
  5. Claude opens an emisar tab. Sign in, review what the connector is asking for, and click Authorize. The connector flips on.
  6. Turn it on for a chat: the + button (lower-left of the composer) → Connectors → toggle emisar.

Team / Enterprise: only an Owner can add the connector, under Settings → Organization settings → Connectors → Add → Custom → Web. Members then open Customize → Connectors and click Connect to run the same sign-in.

ChatGPT

ChatGPT hides custom MCP connectors behind Developer mode, so there's one extra toggle before the connector form appears. Available on Plus, Pro, Business, Enterprise, and Education.

  1. Enable it once: Settings → Apps & Connectors → Advanced settings → turn on Developer mode.
  2. Back in Settings → Apps & Connectors, click Create.
  3. Fill the form:
    • Nameemisar
    • Description — e.g. "Run approved infrastructure actions on my fleet."
    • MCP Server URL https://emisar.dev/api/mcp/rpc
    • Authentication — choose OAuth
  4. Check I trust this application, then click Create. ChatGPT sends you to an emisar sign-in → Authorize.
  5. Use it in a chat: click + near the composer → More, then enable emisar. You may need to re-add it for each new conversation.

ChatGPT connects to remote HTTPS MCP servers only — there is no stdio option. The emisar endpoint is already remote, so nothing extra to host.

What the sign-in grants

The consent screen mints a key bound to your membership. The connector can only run actions your policy already permits, every call is attributed to you in the audit log, and anything needing approval still waits for a human. Revoke access any time from LLM agents in the dashboard, or from the connector settings in Claude / ChatGPT.

2

Mint an API key (desktop, CLI & HTTP)

The clients in steps 3 and 4 authenticate with a raw key instead of OAuth. In the dashboard sidebar, click LLM agents. Pick your LLM client from the tab strip — we mint a key named after it and drop a prefilled snippet you can paste into the client's config. Quick keys are scoped to actions:read + actions:execute (the standard MCP shape).

Want a tighter scope? Pick the Custom tab and restrict which runners or groups the key may target. Keys are revocable and scoped per key. A separate audit:read scope exists for shipping the audit log to a SIEM — it can read events but never execute an action. The dashboard reveals the raw key once — copy and store it.

The cloud connectors in step 1 do not need an API key — they authenticate with OAuth. Mint a key only for the stdio bridge or plain-HTTP clients below.

3

Desktop & CLI clients (stdio bridge)

For clients that only speak stdio MCP — Claude Desktop, Claude Code, Cursor (local mode), Gemini CLI, Codex CLI — install the tiny emisar-mcp binary. It's a thin shim that forwards stdio JSON-RPC frames to the same /api/mcp/rpc endpoint. Every MCP semantic — tool descriptors, content blocks, wait_for_run — is implemented in the portal, so the bridge stays version-locked to the spec without you redownloading it.

Install

One-liner — auto-resolves the latest mcp-v* release, verifies sha256, drops emisar-mcp into /usr/local/bin:

terminal
$ curl -sSL https://emisar.dev/install-mcp.sh | sudo bash

Or go install (Go 1.26+):

terminal
# go install drops the binary at ~/go/bin/mcp; symlink it as emisar-mcp:
$ go install github.com/andrewdryga/emisar/mcp@latest
$ sudo ln -sf ~/go/bin/mcp /usr/local/bin/emisar-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "emisar": {
      "command": "/usr/local/bin/emisar-mcp",
      "env": {
        "EMISAR_URL": "https://emisar.dev",
        "EMISAR_API_KEY": "emk-..."
      }
    }
  }
}

Restart Claude Desktop. Tools appear under the tool icon as "emisar".

Cursor

Same bridge. Cursor reads ~/.cursor/mcp.json:

{
  "mcpServers": {
    "emisar": {
      "command": "emisar-mcp",
      "env": {
        "EMISAR_URL": "https://emisar.dev",
        "EMISAR_API_KEY": "emk-..."
      }
    }
  }
}

Recent Cursor builds also speak remote MCP — point them at /api/mcp/rpc directly (step 1) if you'd rather skip the bridge.

Claude Code

One-line register, user scope (every project):

terminal
$ claude mcp add emisar /usr/local/bin/emisar-mcp \
    --scope user \
    -e EMISAR_URL=https://emisar.dev \
    -e EMISAR_API_KEY=emk-...

Verify with claude mcp list.

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "emisar": {
      "command": "/usr/local/bin/emisar-mcp",
      "env": {
        "EMISAR_URL": "https://emisar.dev",
        "EMISAR_API_KEY": "emk-..."
      }
    }
  }
}

ChatGPT Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.emisar]
command = "/usr/local/bin/emisar-mcp"
env = { EMISAR_URL = "https://emisar.dev", EMISAR_API_KEY = "emk-..." }
4

Plain HTTP / your own agent

Same auth, same data, REST-shaped. Use these when wiring a custom agent (OpenAI tool calling, internal automation, generic curl) with an emk- key from step 2.

terminal
# Try it from a shell — should return the tool list.
$ curl -X POST https://emisar.dev/api/mcp/rpc \
    -H "Authorization: Bearer $EMISAR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  • GET /api/mcp/runners — runners + the actions each advertises.
  • GET /api/mcp/tools — one entry per distinct action with full JSON Schema input descriptor.
  • POST /api/mcp/tools/:action_id?wait=15s — fire-and-forget or long-poll dispatch.
  • GET /api/mcp/runs/:id?wait=60s — fetch result; long-poll for pending approvals.

For OpenAI tool calling: pull /api/mcp/tools, forward each entry's inputSchema as a function parameter schema, and POST the model's chosen arguments back to /api/mcp/tools/:name?wait=30s. Every dispatch must include a reason — it's logged to the audit trail and shown to approvers — and an Idempotency-Key header makes a retry at-most-once.