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.

Before you start, you need:
  • 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. The emisar-mcp bridge is a small binary that sits in between the agent and emisar control plane. Your client starts it, and it passes each call to your account. Install it once per machine — every client uses the same one.

Install#

The installer resolves the latest mcp-v* release, verifies its 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 checks the checksums for you. emisar also publishes a signed attestation for every release, so you can prove the binary came from our source before it runs as sudo. Download the release and run both checks — the attestation names our source repository and the release workflow that built it.

shell 
# provenance — built by our workflow, from our source
$ gh attestation verify emisar-mcp-<version>-linux-amd64.tar.gz --owner andrewdryga
# checksums — the bytes match what we published
$ sha256sum -c SHA256SUMS-MCP

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. Each client config is edited 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 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 to be asked 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 picks up the new server.

A rerun keeps the stored credential until the control plane rejects it. The rest of the command surface — --all, disconnect, --auto-permit — is in MCP CLI & reference.

Set up a client by hand#

When the installer does not support your client, or you would rather edit the config yourself, open Connect an agent in the console and pick the client. It shows the exact config file or command for that client with your key and the endpoint already filled in — the key is shown once, so copy the snippet from there rather than from a docs page that cannot know it.

Direct HTTP — no 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 it after your browser approval or you pasted one by hand, the key is bound to your membership. The agent acts as you. Every call is attributed to you and the agent you are using. It 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 — rotating or minting is the fix, never a lookup. 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 each implies, is in MCP CLI & reference.
  • — The response was lost after a mutation. Recover by operation ID with get_operation, using the same key that made the call — after a rotation, its 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.
  • — 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 August 23, 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.