MCP Server

SuperSpace runs a Model Context Protocol (MCP) server so AI assistants can manage your sites, DNS, domains, and more on your behalf. It is a stateless, OAuth-only, JSON-RPC 2.0 endpoint at POST /mcp on your brand host, exposing a curated subset of the REST API as MCP tools — broad read access plus a small set of safe writes.

Connecting a client

Modern MCP clients connect to SuperSpace directly over remote HTTP — no local bridge or config file required. Point your client at the SuperSpace MCP endpoint and authorize in the browser.

Quick start

There are no headers, tokens, or environment variables to configure up front. After you add the server, your client prompts you to sign in to SuperSpace and authorize access; the token is obtained and stored for you.

Claude (desktop)

Claude supports SuperSpace as a custom connector — no manual configuration needed. See Anthropic's Get started with custom connectors using remote MCP for full details.

1. Open Customize → Connectors → Add custom connector.
2. Give it a Name (for example, SuperSpace).
3. Set the Remote MCP server URL to https://control.superspace.nl/mcp.
4. Click Add.

Once added, Claude prompts you to authenticate with your SuperSpace account to complete the connection.

OpenAI Codex (desktop)

1. Open Settings → MCP Servers → Add Server.
2. Enter the server URL https://control.superspace.nl/mcp. No additional fields are needed beyond the URL.
3. Save.

After saving, Codex prompts you to authenticate with your SuperSpace account to complete the connection.

Transport

• POST /mcp carries the JSON-RPC request. GET, PUT, PATCH, and DELETE return 405 Method Not Allowed.
• The request body is a single JSON-RPC object. Batch arrays are rejected (-32600); malformed JSON returns -32700 (parse error).
• A notification (a request with no id, such as notifications/initialized) returns 202 with an empty body.
• CORS is enabled for /mcp (origins *, methods GET/POST/OPTIONS). A browser Origin, when present, must match the request host or the request is rejected 403 (Origin not allowed); non-browser clients send no Origin, which is allowed.
• The optional MCP-Protocol-Version header, if sent, must be one of 2025-06-18, 2025-03-26, or 2024-11-05, otherwise 400.
• Rate limit: 6000 requests / 10 minutes, keyed per OAuth token.

Authentication

The MCP server accepts only OAuth 2.1 access tokens (session and API-key credentials are refused — see OAuth 2.1). Beyond the normal OAuth checks (brand isolation, account membership, trial accounts are blocked), the token must be audience-bound to this MCP resource per RFC 8707: its resource must equal https://<host>/mcp.

A token issued for the REST API (no resource), or for a different brand's /mcp, is rejected with 401:

{ "jsonrpc": "2.0", "id": null, "error": { "code": -32600, "message": "invalid_token: token audience is not valid for this MCP resource" } }

with the header:

WWW-Authenticate: Bearer resource_metadata="https://<host>/.well-known/oauth-protected-resource/mcp"

The audience is fixed when the token is authorized and is inherited across refreshes. (Conversely, an MCP-audience token is rejected at /api — see Authentication.) mcp-remote performs this audience-bound authorization automatically.

Protected-resource metadata (RFC 9728)

GET /.well-known/oauth-protected-resource
GET /.well-known/oauth-protected-resource/mcp

{
  "resource": "https://<host>/mcp",
  "authorization_servers": ["https://<host>"],
  "scopes_supported": ["sites:read","sites:write","domains:read","domains:write","dns:read","dns:write","billing:read"],
  "bearer_methods_supported": ["header"]
}

A client follows authorization_servers to the authorization-server metadata to discover the authorize and token endpoints, then runs the standard PKCE flow.

JSON-RPC methods

JSON-RPC error codes: -32700 parse error · -32600 invalid request / batch / origin / version / auth · -32601 method not found · -32602 invalid params (unknown tool, insufficient_scope with data.required_scope, missing request_id) · -32603 internal error.

Scopes and tool visibility

Each tool requires an OAuth scope from the same vocabulary as the REST API. tools/list returns only the tools your token's scopes cover. Calling a tool you lack scope for returns a JSON-RPC error inside a 200 response (not an HTTP 403):

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "insufficient_scope", "data": { "required_scope": "sites:write" } } }

Idempotency

Every write tool requires an arguments.request_id (an idempotency key); omitting it returns -32602 (request_id is required for this tool). Calls are de-duplicated per token, tool, and request_id, with a fingerprint of the remaining arguments:

• Replaying a completed call returns the original stored result (no re-execution).
• The same request_id still in flight returns a success result with structuredContent.status = "processing".
• The same request_id with different arguments returns an error result (isError: true) — use a fresh request_id.

Keys are retained for about 24 hours. A few create tools are explicitly non-idempotent because the underlying POST creates a fresh record (a reclaim could duplicate it): create_dns_zone, create_edge_rule, create_waf_custom_rule, create_rate_limit, create_access_list, and activate_shield. Avoid blind retries on those — to change an existing record, use the matching update_* tool. Each tool advertises its behavior in tools/list via annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).

Tool results

A successful tools/call returns both a text block and structured data (the same payload, rendered from the REST API templates so shapes match the documented responses):

{ "content": [ { "type": "text", "text": "<JSON string>" } ], "structuredContent": { }, "isError": false }

Business failures are not JSON-RPC errors — they come back as a normal result with "isError": true and a text message. Secret redaction is applied to both emits: get_site includes site.ssh only if the token also holds sites:write, and get_order always strips SSH data.

Tool catalog

65 tools, all scoped to the authorized account. Reads are broad; writes cover DNS records/zones, site rename and restart, CDN caching and cache purge, edge rules, and the full Shield surface (activate/deactivate, WAF settings and managed/custom rules, rate limits, access lists, bot detection). Below, * marks a required argument and ✎ marks a write tool (which requires a request_id).

Sites

DNS

Domains and registration

Registrar writes (register/transfer, contact CRUD, glue hosts) are not exposed as tools — use the REST API.

CDN, cache, logs, and metrics

Site-scoped. Reads use sites:read; writes use sites:write. CDN reads and writes need a provisioned pull zone (otherwise cdn_not_active).

Edge rules

Site-scoped, CDN active. Reads use sites:read; writes use sites:write. System (CPRESS -) rules are hidden and cannot be created, updated, deleted, or toggled.

Shield

Site-scoped. Reads use sites:read; writes use sites:write. Plan-gated (shield_not_in_plan); reads and writes need a provisioned shield zone (shield_not_active).

Orders and subscriptions

Read-only, scope billing:read.

Advanced: manual installation (stdio bridge)

The mcp-remote bridge runs locally over stdio and proxies to SuperSpace, handling the OAuth login for you (it opens a browser to authorize, then caches the token).

Edit your client's MCP configuration file (for example, claude_desktop_config.json) and add SuperSpace under the mcpServers object:

"superspace": {
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote",
    "https://control.superspace.nl/mcp"
  ]
}

If npx is not on the client's PATH — common, since GUI apps don't inherit your shell environment — and you have mise installed, use it to provide npx:

"superspace": {
  "command": "mise",
  "args": [
    "x",
    "--",
    "npx",
    "-y",
    "mcp-remote",
    "https://control.superspace.nl/mcp"
  ]
}

Then fully restart the client. The first time it connects, a browser window opens for you to authorize via SuperSpace OAuth; approve the account and the connection completes.