Claude Code MCP setup

Claude Code reads project-scoped MCP server definitions from the mcpServers map in a .mcp.json file at the project root. Requests missing the inference scope are rejected at the scope gate with HTTP 403 scope_insufficient before any tool runs.

See the general MCP integration documentation for the full tool catalog, the governed-execution model, the per-client capability matrix, and the security gates (including the XEROTIER_MCP_ENABLED deployment flag and the XEROTIER_MCP_TRANSPORT wire-shape knob) that apply to every MCP request.

Quick Start

Paste the following block into a .mcp.json file at your project root (or merge the mcpServers entry into an existing .mcp.json). This is the documented Claude Code project-scope MCP file. Restart Claude Code and the Xerotier tools appear in the next session.

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.

JSON

                    {
  "mcpServers": {
    "xerotier": {
      "type": "http",
      "url": "https://api.xerotier.ai/proj_ABC123/v1/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>",
        "X-Xerotier-Workspace": "<workspace_external_id>"
      }
    }
  }
}
                

The "type": "http" field is required. Claude Code defaults the transport to stdio when the field is omitted, and the entry will fail to connect.

The URL host and project segment are rendered from your workspace context. Replace the two header placeholders:

<api_key>, a key with the inference scope. Mint one with xeroctl keys --create --scopes inference.
<workspace_external_id>, the ws_xxx identifier of the workspace this connection pins to. List options with xeroctl workspaces list.

Secret handling. The .mcp.json file embeds your workspace API key in the Authorization header, and Claude Code prompts every team member to approve project-scoped servers before use. Add .mcp.json to your project's .gitignore so the key does not land in version control; a leaked key would survive in git history even after rotation.

Generate the bundle automatically. The Xerotier CLI can render this file directly: xeroctl mcp setup --client claude-code emits a ready-to-commit (or, more accurately, a ready-to-gitignore) .mcp.json plus the companion project-rules file documented below.

One-Liner Setup

Claude Code's CLI can install an MCP server entry without hand-editing the config file. The command below registers Xerotier under the project scope and writes the same configuration the manual snippet above produces. The --scope project flag is required: it puts the entry in .mcp.json at the project root rather than the default ~/.claude.json.

bash

                    claude mcp add --transport http --scope project xerotier \
  https://api.xerotier.ai/proj_ABC123/v1/mcp \
  --header "Authorization: Bearer <api_key>" \
  --header "X-Xerotier-Workspace: <workspace_external_id>"
                

Scope options:

--scope project, writes to .mcp.json at the project root and shares the entry with every collaborator who clones the repo (recommended for team projects).
--scope user, writes to the per-user config so the server is visible across every project on this machine.
No --scope flag, defaults to local, written to ~/.claude.json and visible only to your current user in the current project.

Drop the server later with claude mcp remove xerotier.

Recommended Project Rules

Save a .claude/CLAUDE.md file at your project root so Claude Code applies the Xerotier tool-use guidance to every chat in this project. Without it, Claude Code will sometimes ask the user about workspace state instead of calling the MCP tools to retrieve it.

The canonical project-rules block is generated by xeroctl mcp setup --client claude-code alongside the .mcp.json file; the exact body lives in the Xerotier MCP client config renderer as the single source of truth, so always take the latest version from the CLI rather than hand-copying.

Prompts and Resources

The Xerotier MCP surface exposes four prompts and four resources alongside the tool catalog. Claude Code surfaces these in its slash-command and @-mention UI:

Prompts (slash commands)

/mcp__xerotier__session.init, bind the session to a workspace and seed the agent with workspace context.
/mcp__xerotier__brief, pull the current workspace brief (active project, recent decisions, open milestones).
/mcp__xerotier__onboard, run the onboarding flow that prepares the agent for a new chat.
/mcp__xerotier__save-this, persist the current conversation's load-bearing facts as a workspace memory.

Some Claude Code builds render prompts as /xerotier:brief instead of the /mcp__xerotier__brief form; both address the same prompt.

Resources (@-mentions)

@xerotier://workspace/brief, the current workspace brief as a resource.
@xerotier://memory/<slug>, a saved workspace memory by slug.
@xerotier://decisions/recent, the most recent project decisions.
@xerotier://artifact/<id>, a specific artifact by external id.

Recommended Hooks

Claude Code's hook system runs user-supplied scripts at well-defined lifecycle events during a coding session. Hook event names are PascalCase identifiers (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop, SubagentStop, Notification, PreCompact); the exact set is documented by Anthropic at code.claude.com/docs/en/hooks. The Xerotier MCP surface is read-and-write against your workspace memory, so a small amount of hook wiring goes a long way in keeping workspace state in sync with what the agent observes.

PreToolUse

Fires before every tool invocation. Useful for auditing which Xerotier tools the agent calls (e.g. log every xerotier.memory.save to a local journal) or for short-circuiting destructive tools when working in a sensitive workspace.

PostToolUse

Fires after a tool invocation completes. Useful for persisting tool output into a workspace artifact (xerotier.artifact.create) so future sessions can pick up where this one left off, or for refreshing locally cached state when the agent has mutated a workspace. To react specifically to edits Claude Code applies to your project tree, filter PostToolUse on the tool name (Edit, Write, or MultiEdit), there is no separate edit-only event. This is the right place to record load-bearing decisions with xerotier.intelligence.track_decision or capture milestone completions with xerotier.intelligence.track_milestone so the rest of the team sees the change show up in the project brief.

Authoring the hook scripts is out of scope for this document. Refer to the Claude Code hook documentation for the exact event payload shape and the full event catalog.

Client Capabilities

Claude Code's runtime MCP capability set, as surfaced to the Xerotier router during the MCP initialize handshake, is:

sampling: no, the client does not let the server request additional model calls.
elicitation: yes, the server may prompt the user for structured input.
roots: yes, the client advertises a workspace root the server can read against.

See the per-client capability matrix in docs/mcp, Security for the full comparison across every supported client.

Troubleshooting

Tools do not appear in the next session

Claude Code only reloads MCP servers on startup. After editing .mcp.json at the project root, restart the Claude Code CLI; the next tools/list response should include the full Xerotier catalog. If the entry is missing entirely, confirm "type": "http" is present, without it Claude Code interprets the entry as a stdio server and fails silently.

403 Forbidden, inference scope missing

The router rejects requests whose API key does not declare the inference scope at the MCP scope gate, before any tool runs. The response body is:

JSON

                    {
  "error": {
    "type": "authentication_error",
    "code": "scope_insufficient",
    "message": "API key requires 'inference' scope."
  }
}
                

Mint a fresh key with xeroctl keys --create --scopes inference and replace the Authorization header value. A genuine 401 (no code field, or code: "unauthenticated") means the Bearer header is missing or the key has been revoked entirely.

"Workspace not bound" JSON-RPC error

If the X-Xerotier-Workspace header is missing or the session has not been bound to a workspace yet, MCP requests fail with a JSON-RPC invalidRequest error whose message is:

text

                    "Workspace not bound. Call xerotier.session.init or set X-Xerotier-Workspace header."
                

Fix this by either adding the header to your .mcp.json entry as shown in Quick Start, or calling the xerotier.session.init tool (or the /mcp__xerotier__session.init prompt) at the start of the chat. List your workspaces with xeroctl workspaces list to find the correct ws_xxx identifier.