MCP Configuration

Automatic Setup

When you run spiral init or spiral clone, the CLI automatically generates MCP configuration files for every supported IDE. No manual configuration needed.

Manual setup (no CLI)

Spiral MCP is one shared URL per API ({api_base}/mcp). Your project is identified by .spiral/config.json at the workspace root. Create the .spiral directory if it does not exist, then add this file (copy your real project_id from the Spiral dashboard or API):

{
  "project_id": "00000000-0000-0000-0000-000000000001",
  "api_base": "https://api.spirl.sh",
  "version": 1
}

• api_base is the API origin with no trailing slash and no /v1 (e.g. http://localhost:8000).
• MCP url in the next sections must be {api_base}/mcp.
• Agents use this file (or the resolve_project tool) so tool calls include the correct project_id.

Full schema and local examples: repo docs/MCP_WORKSPACE_CONFIG.md.

Cursor

Cursor reads MCP configuration from .cursor/mcp.json in your project root.

{
  "mcpServers": {
    "spiral": {
      "url": "https://api.spirl.sh/mcp",
      "description": "Live project context, drift sync, and context evolution from Spiral"
    }
  }
}

Root key mcpServers. Remote Spiral uses url and optional description only (no type for SSE). The URL is the API's /mcp endpoint; project scope is in .spiral/config.json and tool args. No tokens in this file.

VS Code

VS Code uses root key servers and requires type: "sse" for the remote Spiral entry.

{
  "servers": {
    "spiral": {
      "type": "sse",
      "url": "https://api.spirl.sh/mcp",
      "description": "Live project context, drift sync, and context evolution from Spiral"
    }
  }
}

Authentication

MCP connections are authenticated via OAuth 2.1. The first time your IDE connects to Spiral, a browser window will open asking you to authorize the connection. After you click Authorize, the session is cached — you won't see the popup again.

1. Open your project in Cursor or VS Code
2. The IDE detects the MCP config and connects to Spiral
3. A browser tab opens with the Spiral consent screen
4. Click Authorize — done. All future connections are automatic.

No tokens are stored in configuration files. Authentication is handled entirely by the OAuth flow.

Additional MCP Servers

If your project uses other MCP-compatible tools (database clients, API testing tools, etc.), Spiral can include them in the generated configuration alongside its own server. Configure additional MCP servers in your project settings on the Spiral dashboard.