Connecting an agent

Available

There are two doors into Emithook for an AI agent, and they expose exactly the same tools — one registry, two transports. Which one you want depends on where the agent runs.

	Local (stdio)	Hosted (Connect)
Runs in	Claude Desktop, Cursor, your own process	claude.ai and other hosted clients
Credential	A key you paste, or one from emithook login	An OAuth flow — nothing to paste
Best for	Development, an agent on your own machine	A teammate connecting from a browser

Both end at the same place: an ordinary Emithook API key, visible and revocable in the console like any other. There is no separate "agent credential" to reason about.

Local: stdio

The server runs beside your client and talks to the API with your key.

// Claude Desktop / Cursor MCP config
{
  "mcpServers": {
    "emithook": {
      "command": "npx",
      "args": ["-y", "@emithook/mcp"],
      "env": {
        "EMITHOOK_API_KEY": "ek_live_…",
        "EMITHOOK_SCOPE": "read"
      }
    }
  }
}

Get the key without leaving the terminal:

emithook login            # opens a code you approve in the console
emithook auth whoami      # confirms the active org + identity

EMITHOOK_SCOPE caps which tools are exposed; it never widens what the key can do. Declare read and the write tools are not in the manifest at all, so an agent cannot discover a mutation to attempt. The API enforces the key's real scope regardless — the two are belt and braces, not alternatives.

See the MCP server reference for every environment variable and the full tool catalog.

Hosted: Connect

A hosted client cannot be handed a key to paste, so it runs OAuth instead. You do not configure anything — you click Connect and approve.

The whole exchange:

1. Client POSTs /mcp with no credential
   → 401 WWW-Authenticate: Bearer resource_metadata="https://api.emithook.com/.well-known/oauth-protected-resource"

2. Client reads that document, finds the authorization server, and registers itself
   → POST /oauth/register  (no client secret is ever issued — public clients only)

3. Client sends you to /oauth/authorize with a PKCE challenge
   → you land on a consent screen in the console

4. You approve
   → the browser goes back to the client with a one-time code

5. Client exchanges the code
   → POST /oauth/token, and receives an ordinary Emithook API key

What the consent screen shows you, and why

Three things, and the middle one is the one that matters:

Field	What it tells you
Application	Who says they are asking. Client-supplied — an application can register itself under any name.
Sends you to	The host the authorization code will actually be delivered to. A client cannot fake this.
Access	What the connection gets. Today: read-only.

If the name says one thing and the host says another, that mismatch is the whole signal. Only continue if you recognise the host.

Connections are ordinary keys

After you approve, the connection appears in Developer → API keys alongside every other key, showing how it was minted and which application and host it was granted to. Revoking it there stops the connector on its next call — there is no second revocation story to remember, and last used tells you which connections are still live.

# which key is in use right now, from a terminal
emithook auth keys current

Which tools an agent gets

The catalog is identical across both doors, filtered only by scope. A test asserts the two doors expose the same tool names, so they cannot quietly diverge.

If the agent should…	Give it
Answer questions, investigate, report	read — every list_*, get_*, diagnose_* and metrics tool
Also send, replay, redrive and edit config	write — adds the mutating tools, each still requiring confirm: true
Rotate secrets and perform destructive operations	admin

Start at read. It is the only scope where "the agent did something unexpected" cannot mean "the agent changed something".

See also

• MCP server — the full tool catalog and when to reach for each.
• Agent workflows — diagnosing a failure and reading the numbers.
• CLI — emithook guide prints the whole surface in one page.