MCP server: SovrGPT in Cursor, Claude Desktop and Zed

The Model Context Protocol (spec) lets you connect SovrGPT to Cursor, Claude Desktop, Zed or Windsurf. There are two servers:

Both speak Streamable HTTP (MCP 2025-03-26). Older clients can use SSE at /mcp/docs/sse and /mcp/sse respectively.

Documentation MCP (public)

Tools:

• sovrgpt_docs_list_pages: list all documentation pages
• sovrgpt_docs_search: full-text search across all documentation pages
• sovrgpt_docs_get_page: read a page as Markdown

No API key required. The server is meant for editor models that connect your code to SovrGPT, for example during a migration or to look up new model IDs.

Language: every tool takes an optional language parameter (de or en, default de). Pages without an English version come back in German marked translated: false, so a model can say so instead of silently switching language.

Platform MCP (with API key)

Authentication: create a sov_… key with scope mcp under Settings → API keys and send it as a bearer token. Without that scope the server rejects the connection itself with 401.

Scope rule for sovrgpt_decide: the mcp scope opens the connection; a decision also needs decisions (the same permission as POST /v1/decisions). Without it the tool answers { "status": "failed", "code": "missing_scope" }, and the other tools keep working with the same key. So tick Decision Engine when you create the key.

Every answer carries a recommendation recommendation ("act" or "review") and its warning signals in reasons. The legacy fields abstain and abstain_reasons remain; abstain is true exactly when the recommendation is "review". The default is policy.mode = "threshold" (threshold 0.85, double check of choice questions on): "review" only appears with warning signals. Until 23 Sep 2026 every answer carried abstain: true.

• policy.mode = "review_only": every recommendation is "review". Use it if an editor model must not act on anything unreviewed.
• policy = { "mode": "review_only", "stability_check": false }: exactly the old behaviour at the old cost, without the double check.
• policy.mode = "autonomous": every recommendation is "act"; the warning signals are still listed in reasons.

Probabilities are not calibrated (calibration.status = "uncalibrated"). Details: Automatic or human.

Setup per client

Cursor

Cursor Settings → MCP → Add new global MCP server:

{
  "mcpServers": {
    "sovrgpt-docs": {
      "url": "https://sovrgpt.com/mcp/docs/mcp"
    },
    "sovrgpt": {
      "url": "https://sovrgpt.com/mcp/mcp",
      "headers": {
        "Authorization": "Bearer sov_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Save, restart Cursor, then type @ in the chat and check the tool list. The sovrgpt_* tools show up right away.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "sovrgpt-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://sovrgpt.com/mcp/docs/mcp"]
    },
    "sovrgpt": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://sovrgpt.com/mcp/mcp",
        "--header",
        "Authorization:Bearer sov_xxxxxxxxxxxxxxxx"
      ]
    }
  }
}

mcp-remote (npm) bridges Claude's stdio transport to Streamable HTTP. Restart Claude Desktop afterwards.

Zed

~/.config/zed/settings.json:

{
  "context_servers": {
    "sovrgpt-docs": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-remote", "https://sovrgpt.com/mcp/docs/mcp"]
      }
    },
    "sovrgpt": {
      "command": {
        "path": "npx",
        "args": [
          "-y", "mcp-remote",
          "https://sovrgpt.com/mcp/mcp",
          "--header", "Authorization:Bearer sov_xxxxxxxxxxxxxxxx"
        ]
      }
    }
  }
}

Windsurf

Settings → Cascade → MCP servers → Add server → Streamable HTTP. URL and header as for Cursor.

Notes

• No streaming: sovrgpt_chat returns the answer as a single tool result. For live streaming use the REST API (/api/v1/chat/completions with stream:true).
• Image/video polling: in the pending case the tool result contains a poll_url field (/api/image/<id> or /api/video/job/<id>). Query it with GET and the same key: Authorization: Bearer sov_…, scope mcp, no cookie. Every answer is a 200 with a status field. pending means keep polling (images about every 5 s, video about every 10 s). succeeded (image) or done (video) returns the result in signedUrl; the URL is valid for an hour, and polling again issues a fresh one. failed gives the reason in error. Note: the tool result reports success as complete, the poll response as succeeded or done, so do not wait for complete when polling.
• Cold starts: on the first call to a cold, self-operated model, sovrgpt_chat waits up to 13 minutes. The default tier, which the tool uses without model, has a cold start too. Use sovrgpt_list_models to find a model whose cold_start_hint says "kein Kaltstart" (no cold start) and pass its ID as model.
• Decision Engine: sovrgpt_decide expects exactly one of state and messages; preset and questions are mutually exclusive. Presets whose example_state is a JSON string (antrag-vollstaendigkeit-v1, grounding-check-v1, agent-step-risk-v1) expect a JSON object as state. A decision typically takes well under a second, and there is no cold start. If it fails, you get { "status": "failed", "code": … } with a code from the error table. upstream_rate_limited means the runtime is throttling right now: wait briefly and retry. If only the second pass of the double check fails, that is not an error; the answer arrives with stability: null and the warning signal stability_unavailable. More: Decision Engine; contract: POST /v1/decisions.
• Billing: every tool call counts against your organisation's monthly budget, as with the REST API. As the source (usage_events.source), chat is recorded as mcp, images and video as image or video. sovrgpt_decide is recorded as decisions-mcp, billed by the runtime's input tokens as with POST /v1/decisions. Web search creates no cost row.

Security

Keys in the Authorization: Bearer header are verified server-side only and stored only as a SHA-256 hash. You can revoke a key at any time under Settings → API keys; the next call then fails immediately with 401. We recommend a separate key per client.