Cursor MCP setup - Xerotier

Cursor reads its MCP configuration from .cursor/mcp.json in your project root. Each entry carries a url, a Bearer key, and the workspace-pin header that every other Xerotier MCP client uses. Cursor infers the streamable-HTTP transport from the presence of url; there is no explicit type discriminator on remote servers (the type field is only documented on local stdio servers).

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.

Quick Start

The fastest path is to let xeroctl render the exact, vendor-correct snippet from the same source of truth the dashboard download uses:

bash

xeroctl mcp setup --client cursor --workspace ws_<id> > .cursor/mcp.json

This command defaults to env-var indirection (Bearer {env:XEROTIER_API_KEY}), which keeps the raw key out of the repository. Export XEROTIER_API_KEY in your shell profile before launching Cursor. Pass --inline-api-key if you must embed the literal key (not recommended for repos under version control).

If you do not have xeroctl installed, paste the following block into .cursor/mcp.json at your project root (create the file if it does not yet exist). Restart Cursor and the Xerotier tools appear in the agent's tool list on the next session.

JSON

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

Replace the placeholders:

<workspace_external_id>, the ws_-prefixed 24-hex identifier of the workspace this connection pins to. List options with xeroctl workspaces list.
XEROTIER_API_KEY, exported in your shell, holding a key minted with the inference scope. Create one with xeroctl keys --create --name "Cursor MCP" --scopes inference.

The url already contains your project id; the dashboard renders it inline above. The {env:VAR} form is Cursor's env-indirection syntax, the agent resolves it from your shell environment at session start, so the literal key never lands in the config file.

A fully-substituted example with real-shaped ids:

JSON

                    {
  "mcpServers": {
    "xerotier": {
      "url": "https://api.xerotier.ai/prj_a1b2c3d4e5f607182939404142/v1/mcp",
      "headers": {
        "Authorization": "Bearer {env:XEROTIER_API_KEY}",
        "X-Xerotier-Workspace": "ws_a1b2c3d4e5f607182939404142"
      }
    }
  }
}
                

To use the literal-key form instead, replace {env:XEROTIER_API_KEY} with the raw key string. Cursor also accepts user-level MCP configuration at ~/.cursor/mcp.json; use the same shape if you want the Xerotier server available across every project on the machine.

Security: if you embed an inline key, .cursor/mcp.json contains a live workspace credential. Add .cursor/ to your project's .gitignore so the file does not land in version control. The env-var form above sidesteps this risk entirely.

Agent Rules File

Cursor's agent picks tools based on the live tool list, but a one-paragraph nudge in a project rules file makes the Xerotier-specific workflows discoverable faster. The current Cursor format is .cursor/rules/xerotier.mdc with an alwaysApply: true front-matter block. Drop something like the following at that path:

Markdown

                    ---
alwaysApply: true
---
This workspace is connected to Xerotier MCP. Prefer
xerotier.memory.search and xerotier.intelligence.brief
when answering questions about prior decisions, project
history, or workspace state. Record load-bearing
decisions with xerotier.intelligence.track_decision and
completed milestones with xerotier.intelligence.track_milestone
before moving on to the next task.
                

The legacy .cursorrules file at the project root is still honored by Cursor as a fallback, but new projects should prefer the .cursor/rules/*.mdc form. Tune the wording to match the surface area you expect the agent to lean on most.

Prompts and Resources

The Xerotier MCP server exposes more than just tools: it also publishes 4 prompts and 4 resources that Cursor surfaces through its @ picker. Invoke a prompt with @xerotier <prompt-name>; attach a resource with @xerotier://<resource-uri>.

Prompts

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

Resources

@xerotier://workspace/current/brief, the current workspace brief as a resource.
@xerotier://workspace/current/recent-decisions, the rolling decisions feed (accepts ?since=7d&limit=20).
@xerotier://memory/<slug>, a saved workspace memory by slug.
@xerotier://artifact/<id>, a specific artifact by external id.

Mentioning this syntax in your .cursor/rules/xerotier.mdc file significantly accelerates how quickly the agent discovers the prompt and resource surface.

Troubleshooting

Tools do not appear after editing the config

Cursor reloads MCP servers on startup. After editing .cursor/mcp.json, restart Cursor or use the in-app "Reload MCP server list" action; the next tools/list response should include the full Xerotier catalog.

401 Unauthorized on every tool call

The bearer credential failed authentication: the API key is missing, malformed, or has been revoked. Confirm XEROTIER_API_KEY is exported in the shell that launched Cursor (or, for the inline form, that the literal key in .cursor/mcp.json is current). Mint a fresh key with xeroctl keys --create --name "Cursor MCP" --scopes inference if the previous one was rotated or revoked.

403 Forbidden with code scope_insufficient

The key authenticated successfully but does not carry the inference scope. The response body has the shape:

JSON

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

Mint a replacement key that includes the scope: xeroctl keys --create --name "Cursor MCP" --scopes inference, then update XEROTIER_API_KEY (or the inline header value) and restart Cursor.

Workspace not bound or workspace mismatch

The pinned X-Xerotier-Workspace header is missing, malformed, or names a workspace in a different project than the API key. On the tools/call path this surfaces as HTTP 403; on the prompts/get and resources/read paths it surfaces as a JSON-RPC invalidRequest error whose message is:

text

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

List your workspaces with xeroctl workspaces list and confirm the ws_-prefixed id matches the project the key was minted under. If the header is correct but the session has not yet been bound, call the xerotier.session.init tool (or the @xerotier session.init prompt) at the start of the chat.

Quick Start

Agent Rules File

Prompts and Resources

Prompts

Resources

Troubleshooting

Tools do not appear after editing the config

401 Unauthorized on every tool call

403 Forbidden with code scope_insufficient

Workspace not bound or workspace mismatch

See Also