Evenbead docs
Contents

MCP setup

Evenbead runs a remote MCP server at https://api.evenbead.com/mcp (Streamable HTTP transport, JSON responses, stateless). Every tool is one API operation run through the same pipeline as REST: the same key, scopes, idempotency, dry runs, proposals and audit log. The full list is in MCP tools.

Authenticate with an API key in the Authorization header. Use an agent's key, not a person's, so writes follow the agent's policy and the audit log shows the agent.

Claude Code

claude mcp add --transport http evenbead https://api.evenbead.com/mcp \
  --header "Authorization: Bearer $EVENBEAD_AGENT_KEY" \
  --header "X-Agent-Model: claude-opus-5-5"

Add --scope project to share the server definition with a repository (keep the key itself out of the repository: reference an environment variable). Check it with claude mcp list, then ask Claude to call whoami.

Claude Desktop

Claude Desktop's custom connectors expect OAuth, which Evenbead does not offer yet. Use a local bridge that adds the header, such as the open-source mcp-remote package (needs Node.js). In claude_desktop_config.json:

{
  "mcpServers": {
    "evenbead": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.evenbead.com/mcp",
               "--header", "Authorization:${EVENBEAD_AUTH}",
               "--header", "X-Agent-Model:${EVENBEAD_MODEL}"],
      "env": { "EVENBEAD_AUTH": "Bearer eb_...", "EVENBEAD_MODEL": "claude-desktop" }
    }
  }
}

The values sit in env without spaces around the colon because some clients split arguments on spaces. Restart Claude Desktop after editing the file.

Other clients

Any MCP client that supports the Streamable HTTP transport and custom request headers can connect directly: URL https://api.evenbead.com/mcp, header Authorization: Bearer <key>. Clients that only speak stdio can use the same bridge as above.

What the server expects

  • Protocol versions: 2026-07-28 (stateless: each request carries its version in _meta and the MCP-Protocol-Version header) and the earlier 2025-11-25, 2025-06-18 and 2025-03-26 (initialize, then tools). No sessions are issued.
  • Agent identity: the X-Agent-Model and X-Agent-Run-Id headers, or _meta keys dev.evenbead/model and dev.evenbead/run_id on each call. Agent writes without a model are refused with model_required.
  • Writes: pass an idempotency_key argument (8 to 200 characters). Reuse it when retrying.
  • Previews: write tools accept dry_run: true.
  • Firms: firm keys name the client with the X-Evenbead-Company header or _meta key dev.evenbead/company.
  • Errors: a failed tool call returns isError: true with the API's error body, so the model can read error.type and correct itself.
  • Browser requests from other origins are refused.

A first session

  1. whoami: confirms the key, the company and the scopes.
  2. list_accounts: the chart of accounts.
  3. propose_journal_entry with dry_run: true: see the verdict.
  4. The same call with an idempotency_key: it posts, or waits in the approval queue for a person.