MCP server (Model Context Protocol)

SovrGPT publishes two MCP servers (Model Context Protocol, spec):

Both endpoints speak Streamable HTTP (MCP 2025-03-26). For older clients there is also SSE at /mcp/docs/sse and /mcp/sse respectively.

Documentation MCP (public)

Tools:

• sovrgpt_docs_list_pages — list all MDX pages
• sovrgpt_docs_search — full-text search across the docs and docs/api-reference.md
• sovrgpt_docs_get_page — read a page as Markdown
• sovrgpt_docs_api_endpoints — enumerate the REST endpoints

No API key required. Intended for editor models that are supposed to integrate your code with SovrGPT (migration, routing, looking up new model IDs).

Language: every tool takes an optional language parameter (de or en, default de). Pages that have no English version are returned in German and marked with translated: false, so a model can say so instead of silently switching language.

Platform MCP (authenticated)

Tools:

Auth: create a sov_… API key under Settings → API keys (scope mcp) and pass it as a bearer token. Without that scope the platform MCP server rejects the connection itself with 401. Quota and cost logging works identically to the REST API (/api/v1/chat/completions).

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 from 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 responses: the MCP wrapper delivers sovrgpt_chat results 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 output 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 needed. Every answer is a 200 with a status field: pending means keep polling (images every ~5 s, video every ~10 s), succeeded (image) or done (video) returns the result in signedUrl (valid for one hour; polling again issues a fresh URL), failed gives the reason in error. ⚠️ The success word differs between the tool output (complete) and the poll response (succeeded/done) — do not wait for complete.
• Cold starts: sovrgpt_chat blocks for up to 13 minutes on the first call to a cold tier. Load the tiers via sovrgpt_list_models and pick a warm tier (usually default).
• Logging: every MCP tool call is recorded in usage_events.source = 'mcp' and counts against the org's monthly budget — identically to the REST API.

Security

API keys passed in the Authorization: Bearer header are verified server-side only (api_keys table, SHA-256, RLS). You can revoke them at any time via Settings → API keys — the MCP server rejects the next call immediately with 401. We recommend a separate key per client.