docs
// Guides

Claude Desktop

User-level config, not per-project. Every workspace you want to reach from Claude Desktop lives in one claude_desktop_config.json, keyed uniquely so multiple Erebine workspaces coexist without overwriting each other on the next reload.

Claude Desktop reads its MCP configuration from claude_desktop_config.json under your user-level Claude support directory. The same streamable HTTP transport, Bearer key, and workspace-pin header used by every other MCP client applies.

See the general MCP integration documentation for the full tool catalog, the governed-execution model, and the security gates that apply to every MCP request.

Claude Code is recommended for most workflows. Claude Desktop's HTTP MCP support is functional but less polished than Claude Code's; if you have the choice, the Claude Code CLI gives the smoother integration. Use Claude Desktop when a graphical conversation surface is the right primary interface.

Quick Start

Locate the Claude Desktop configuration file for your platform:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Required scope. The API key in the Authorization header must declare the inference scope. Without it the router returns HTTP 403 with error.code: "scope_insufficient" at the scope gate, before any tool call is dispatched.

Merge the following block into the file (create the file if it does not yet exist, and add the mcpServers key if you already have other top-level Claude Desktop settings). Quit and relaunch Claude Desktop; the Erebine tools appear on the next session.

JSON
{ "mcpServers": { "erebine-<workspace_external_id>": { "url": "https://api.erebine.ai/proj_ABC123/v1/mcp", "headers": { "Authorization": "Bearer <api_key>", "X-Erebine-Workspace": "<workspace_external_id>" } } } }

Replace the two placeholders. The path segment proj_ABC123 is your project's external id, already substituted into the URL above for the project you are signed into.

  • <api_key>, a key with the inference scope. Mint one with erectl keys --create --name "Claude Desktop" --scopes inference.
  • <workspace_external_id>, the ws_xxx identifier of the workspace this server entry pins to. The same value appears in the server key and in the X-Erebine-Workspace header. List options with erectl workspaces list.

Generate the bundle automatically. The Erebine CLI can render this file directly: erectl mcp setup --client claude-desktop emits a ready-to-merge claude_desktop_config.json entry with your project id and a freshly minted inference key already substituted in.

Multiple Workspaces

Because Claude Desktop has no per-project scoping, the server entry's key is the only thing distinguishing one Erebine workspace from another. The example above uses erebine-<workspace_external_id> rather than a flat erebine: that makes the key unique per workspace, so you can paste a second block for another workspace without overwriting the first.

JSON
{ "mcpServers": { "erebine-ws_alpha": { "url": "https://api.erebine.ai/proj_demo/v1/mcp", "headers": { "Authorization": "Bearer ere_demo_abc...", "X-Erebine-Workspace": "ws_alpha" } }, "erebine-ws_beta": { "url": "https://api.erebine.ai/proj_demo/v1/mcp", "headers": { "Authorization": "Bearer ere_demo_abc...", "X-Erebine-Workspace": "ws_beta" } } } }

Each entry advertises the full tool catalog scoped to its pinned workspace, and Claude Desktop surfaces them as separate tool groups. The agent picks the right group based on tool name prefixes.

Prompts and Resources

The Erebine MCP server exposes more than tools: each workspace also advertises 6 prompts and 4 resources alongside the tool catalog. Claude Desktop's MCP client currently surfaces resources through its @-mention attachment picker but does not render prompts as slash commands.

Resources (@-mentions)

Type @ in the composer and pick the Erebine server; resources are addressed with the URI form below.

  • @erebine://workspace/current/brief, the always-current workspace brief.
  • @erebine://workspace/current/recent-decisions, the rolling decisions feed.
  • @erebine://memory/<slug>, a saved workspace memory by slug.
  • @erebine://artifact/<id>, a specific artifact by external id.

Prompts

Claude Desktop does not render MCP prompts in its UI today. The prompts remain reachable from clients that do (Claude Code, Cursor), and are documented on the general MCP integration page. When Anthropic ships prompt support in Claude Desktop, no config change is required, the prompts will appear automatically.

Capability Matrix

Claude Desktop's MCP capability set, as surfaced to the Erebine router during the MCP initialize handshake, is:

  • transport: streamable HTTP.
  • authorization: Bearer header.
  • custom headers: yes, used for the X-Erebine-Workspace pin.
  • resources: yes, surfaced through the @-attach picker.
  • prompts: no, prompts are not rendered as slash commands.
  • sampling: no, the client does not let the server request additional model calls.
  • elicitation: no, the client does not expose a structured-input prompt to the server.
  • roots: no, no workspace root is advertised to the server.

See the full per-client comparison in docs/mcp, Security.

Troubleshooting

Tools do not appear after editing the config

Claude Desktop only reloads MCP servers on startup. Fully quit and relaunch the application after editing claude_desktop_config.json; the next tools/list response should include the full Erebine catalog.

Server entries collide when pasting a second workspace

The server key (mcpServers.<key>) must be unique inside the map. If you reuse erebine for two workspaces, only the second entry takes effect. Use erebine-<workspace_external_id> instead.

401 Unauthorized on every tool call

The API key is missing, malformed, or has been revoked. Mint a fresh key with erectl keys --create --name "Claude Desktop" --scopes inference and replace the Authorization header value.

403 Forbidden with code scope_insufficient

The API key authenticated but does not carry the inference scope required by the MCP surface. The response body's code field is scope_insufficient and type is authentication_error. Mint a replacement key with the inference scope using the command above.

403 Forbidden referencing workspace mismatch

The pinned X-Erebine-Workspace identifier does not belong to the same project as the API key. List your workspaces with erectl workspaces list and confirm the ws_xxx id matches the project the key was minted under.