Skip to main content
emisar
Docs navigation

Get started

CLI agent

Connect a local AI client to your action catalog through direct HTTPS or the emisar-mcp stdio bridge.

Using Claude.ai or ChatGPT instead? Those connect over OAuth with no key or bridge to manage. See Connect a cloud LLM.

Want to limit what your agent can access on your computer? We recommend co:op. Follow Agent sandboxes to compare the supported options.

Before you start, you need:
  • Your AI app installed on the computer where you will run the bridge.
  • An account with at least one runner online. Otherwise the agent signs in fine and finds an empty catalog with nothing to call. New here? Run the quickstart first, then come back to wire in your client.
Use your coding agent

The connect-llm skill walks your agent through this whole page.

paste into your agent 
Connect this machine's coding agent to my emisar account over MCP — install the emisar-mcp bridge, register the client, and prove a run end to end. First ask me which client I use. Use the connect-llm skill: https://raw.githubusercontent.com/AndrewDryga/emisar/main/skills/connect-llm/SKILL.md

Works in Claude Code, Codex, or any agent that reads Markdown skills. Read the skill first .

Set up a stdio client#

Most local clients speak stdio (standard input and output). The emisar-mcp bridge is a small binary that sits between the agent and the emisar control plane. Your client starts it, and the bridge passes each call to your account. Install it once per machine. Every client uses the same one.

Install#

The installer finds the latest mcp-v* release, authenticates its signed checksum, and installs emisar-mcp into /usr/local/bin on macOS and Linux, and %LOCALAPPDATA%\Programs\Emisar\bin on 64-bit Windows: 

$ curl -fsSL https://emisar.dev/install-mcp.sh | sudo bash
Verify this download first

The installer runs these checks before the binary can run as sudo. Bundle verification uses GitHub CLI with gh attestation verify --bundle. Without GitHub CLI, the installer asks before continuing on the checksum alone, or warns and continues when run unattended. GitHub CLI needs no GitHub login, but a fresh cache loads public trust roots from the hosts listed under Network requirements. 

# signed checksum metadata — produced for this tag by the trusted workflow
$ gh attestation verify SHA256SUMS-MCP --bundle SHA256SUMS-MCP.sigstore.jsonl \
  --repo andrewdryga/emisar \
  --signer-workflow AndrewDryga/emisar/.github/workflows/mcp-release-trusted.yml \
  --source-ref refs/tags/mcp-v<version> \
  --deny-self-hosted-runners
✓ Verification succeeded!
…
# archive bytes — match the authenticated checksum
$ awk -v file='emisar-mcp-<version>-linux-amd64.tar.gz' \
  '$2 == file { print; found=1 } END { exit !found }' SHA256SUMS-MCP \
  | sha256sum -c -
emisar-mcp-<version>-linux-amd64.tar.gz: OK
…

More on the signing pipeline: Release integrity.

The installer then runs emisar-mcp connect, which finds the supported clients on this machine and asks about each one. Browser approval creates one key for direct emisar-mcp commands and a separate key for each client you pick. Direct commands then work without shell-profile exports. The command edits each client config in place, so its comments, settings, and other MCP servers are untouched. See Use MCP tools from the shell.

Targeting a signed-dispatch runner? If a runner enforces signed dispatch, the bridge needs EMISAR_SIGNING_KEY and EMISAR_SIGNING_CERT in its environment. Put them wherever your client passes environment variables to the bridge: the env block in its config file, or another -e flag if you registered it with claude mcp add or grok mcp add. emisar signing init prints both values. The bridge signs each action dispatch. Keep both values secret and off the portal.

Connect a client you install later#

emisar-mcp connect is an ordinary command, so a client you install next month does not need a reinstall. Run it with no arguments, and it asks about each client it finds. Or name one directly. A client that already carries an emisar entry is left alone:

shell 
$ emisar-mcp connect --client zed

Connect emisar

  Emisar CLI      credential verified
  Claude Code     already connected
  Cursor          already connected
  Codex CLI       already connected
  Zed             not connected

Approve this machine in your browser

  https://emisar.dev/activate?code=FKZQ-2418

If prompted, enter this code: FKZQ-2418

Sent the link to your default browser. If it did not open, use the link above.

Waiting for approval (Ctrl-C to cancel)…

  Zed             connected → /home/operator/.config/zed/settings.json

Restart any client you just connected so it starts using the new server.

A rerun keeps the stored credential until the control plane rejects it. The other commands and flags (--all, disconnect, --auto-permit) are in MCP CLI & reference.

Set up a client by hand#

  1. Open Connect an agent, select your app, and expand Set up manually.
  2. Download the bridge for your operating system and processor. Extract the archive, keep the executable in a permanent folder, and enter its full path. If you already installed the bridge, use its existing path. Run the version command shown below the field; it should print the bridge's version.
  3. Follow the app's configuration instructions. Your key and endpoint are already filled in. For a configuration file, merge the snippet with existing settings; do not replace other servers. Create the file and any missing folders if needed, then save it. For a command, run it in the terminal shown. VS Code asks for the API key separately when its server starts.
  4. Follow the app's Check the connection steps to start the server and approve any connection prompts. Then send the example prompt to your app. The console shows Agent connected after the app makes its first call.

Save your configuration before leaving the setup page. The key is shown only during setup; keep the configuration private.

Client-specific requirements#

  • Claude Desktop: use Settings → Developer → Edit Config to open the right file on your platform. Fully quit and reopen the app after saving. These settings connect Desktop Chat, not the Code tab.
  • VS Code: this setup uses the Local chat target and Agent role. The Copilot session target cannot use its interactive API-key prompt; configure it through the Copilot CLI option on Connect an agent instead.
  • Gemini CLI: MCP servers do not connect in untrusted folders. Review the folder-trust prompt before trusting the folder, then run /mcp to check emisar's connection.
  • Pi: install Pi first, then add the third-party pi-mcp-adapter with pi install npm:pi-mcp-adapter. After saving the configuration, restart Pi and run /mcp reconnect emisar. Follow Pi's installation guide for its Node.js and platform requirements.
  • Hermes and Goose on Windows: use manual setup and the Windows configuration path shown in the console.

Direct HTTP without a bridge#

Any MCP client that supports Streamable HTTP and a custom authorization header can connect straight to emisar. There is no bridge binary to install.

  1. Open Connect an agent and select Custom. Create a dedicated key and copy it before leaving the page. The key is shown once.
  2. Add an MCP server to your client, choose the Streamable HTTP transport, and give it these two values:

Server URL

https://emisar.dev/api/mcp/rpc

Authorization header

Authorization: Bearer emk-...

Replace emk-... with the key you copied. Store it in the client's secret or user-level configuration. Do not commit it in a project configuration file.

What direct HTTP leaves out

A direct HTTP client cannot sign dispatches and does not rotate its agent key automatically. Use the stdio bridge when a runner requires signed dispatch. Rotate or revoke a direct client's key from AI agents.

Verify the connection#

  1. Restart or reconnect the client after its config changes.
  2. Confirm that the client lists the emisar MCP tools.
  3. Ask it to run linux.uptime on any one of the connected runners.
  4. Confirm that the client returns the action output.
  5. Open Audit. Confirm that the event records the client, runner, action, and reason.

What the sign-in grants#

Whether the installer minted the key after your browser approval or you pasted one by hand, it is bound to your membership. The agent acts as you. Every call is attributed to you and the agent you are using. The key reaches only the runners and actions your own access already allows (how a key inherits its operator's scope). Revoke it any time from AI agents in the console. Manage agents & keys covers rotation.

Troubleshooting#

The LLM client or the bridge#

  • — Every call returns 401. The key expired, was revoked, or was retired when its rotation successor made its first call. A secret is shown only once and cannot be viewed again, so a failing client always needs a fresh one: rotate the key or mint a new one. A revoked key cannot be restored. If the client never worked at all, check which token was copied: an audit-export token starts emk-export-, and the MCP endpoint refuses it as the wrong kind. Mint or rotate a key in AI agents and put the new secret in the client config. For a client the bridge configured, emisar-mcp connect --client <id> does both steps in one go. Manage agents & keys covers scope and expiry. Rotate and revoke credentials covers the cutover.
  • — The bridge is outdated or unsupported. The AI agents page shows the version each key last reported, and emisar-mcp --version shows what is installed. A running client keeps the binary it already loaded, so restart the client after installing. See Upgrade the MCP bridge.
  • — A tool call comes back with an error code. invalid_args returns the exact paths to correct, so fix those rather than retrying the same call. The complete code list, with the one action to take for each, is in MCP CLI & reference.
  • — The response was lost after a mutation (a call that changed something). Recover by operation ID with get_operation, using the same key that made the call. After a rotation, the key's successor counts. Never repeat the mutation. Cancelling only stops the bridge's wait, and closing the client lets requests already in flight finish, so a cancelled call, closed client, or dropped bridge does not undo work the control plane already admitted.
  • — On Team or Enterprise, contact support when the same tool returns a transport error on every attempt. Also contact support when a recorded operation ID is missing under the credential that created it.

← Previous

Runner credentials

Next →

Claude.ai

Last reviewed September 6, 2026

Point your agent at real infrastructure — safely.

Set up a runner first, then connect Claude Code, Cursor, or any MCP client to your account's endpoint and let policy decide what runs.

Start free Read the quickstart

Three runners. Seven-day audit. No credit card.