MCP-server

SuperSpace draait een Model Context Protocol (MCP)-server zodat AI-assistenten namens jou je sites, DNS, domeinen en meer kunnen beheren. Het is een stateless, OAuth-only, JSON-RPC 2.0-endpoint op POST /mcp op je merk-host, dat een zorgvuldig samengestelde subset van de REST API blootstelt als MCP-tools — brede leestoegang plus een kleine set veilige writes.

Een client verbinden

Moderne MCP-clients verbinden rechtstreeks met SuperSpace via remote HTTP — geen lokale bridge of configuratiebestand vereist. Wijs je client naar het SuperSpace MCP-endpoint en autoriseer in de browser.

Snel starten

Er zijn vooraf geen headers, tokens of omgevingsvariabelen te configureren. Nadat je de server hebt toegevoegd, vraagt je client je om in te loggen bij SuperSpace en toegang te autoriseren; de token wordt voor je opgehaald en opgeslagen.

Claude (desktop)

Claude ondersteunt SuperSpace als een custom connector — geen handmatige configuratie nodig. Zie Anthropic's Get started with custom connectors using remote MCP voor alle details.

1. Open Customize → Connectors → Add custom connector.
2. Geef het een Name (bijvoorbeeld SuperSpace).
3. Stel de Remote MCP server URL in op https://control.superspace.nl/mcp.
4. Klik op Add.

Eenmaal toegevoegd vraagt Claude je om je te authenticeren met je SuperSpace-account om de verbinding te voltooien.

OpenAI Codex (desktop)

1. Open Settings → MCP Servers → Add Server.
2. Voer de server-URL https://control.superspace.nl/mcp in. Er zijn naast de URL geen extra velden nodig.
3. Sla op.

Na het opslaan vraagt Codex je om je te authenticeren met je SuperSpace-account om de verbinding te voltooien.

Transport

• POST /mcp draagt het JSON-RPC-verzoek. GET, PUT, PATCH en DELETE geven 405 Method Not Allowed terug.
• De request-body is een enkel JSON-RPC-object. Batch-arrays worden geweigerd (-32600); misvormde JSON geeft -32700 (parse error) terug.
• Een notificatie (een verzoek zonder id, zoals notifications/initialized) geeft 202 terug met een lege body.
• CORS is ingeschakeld voor /mcp (origins *, methoden GET/POST/OPTIONS). Een browser-Origin, indien aanwezig, moet overeenkomen met de request-host, anders wordt het verzoek geweigerd met 403 (Origin not allowed); niet-browserclients sturen geen Origin, wat is toegestaan.
• De optionele MCP-Protocol-Version-header moet, indien meegestuurd, een van 2025-06-18, 2025-03-26 of 2024-11-05 zijn, anders 400.
• Rate limit: 6000 verzoeken / 10 minuten, gekoppeld per OAuth-token.

Authenticatie

De MCP-server accepteert alleen OAuth 2.1-accesstokens (session- en API-sleutel-credentials worden geweigerd — zie OAuth 2.1). Naast de normale OAuth-controles (merkisolatie, accountlidmaatschap, proefaccounts worden geblokkeerd) moet de token audience-bound aan deze MCP-resource zijn volgens RFC 8707: de resource moet gelijk zijn aan https://<host>/mcp.

Een token dat is uitgegeven voor de REST API (geen resource), of voor de /mcp van een ander merk, wordt geweigerd met 401:

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

met de header:

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

De audience wordt vastgelegd wanneer de token wordt geautoriseerd en wordt overgeërfd over refreshes heen. (Omgekeerd wordt een MCP-audience-token geweigerd op /api — zie Authenticatie.) mcp-remote voert deze audience-bound autorisatie automatisch uit.

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"]
}

Een client volgt authorization_servers naar de authorization-server-metadata om de authorize- en token-endpoints te ontdekken, en draait dan de standaard PKCE-flow.

JSON-RPC-methoden

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

Scopes en zichtbaarheid van tools

Elke tool vereist een OAuth-scope uit hetzelfde vocabulaire als de REST API. tools/list geeft alleen de tools terug die de scopes van je token dekken. Het aanroepen van een tool waarvoor je geen scope hebt, geeft een JSON-RPC-fout binnen een 200-response terug (geen HTTP 403):

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

Idempotency

Elke write-tool vereist een arguments.request_id (een idempotency-sleutel); het weglaten ervan geeft -32602 (request_id is required for this tool) terug. Aanroepen worden gededupliceerd per token, tool en request_id, met een fingerprint van de overige argumenten:

• Het herhalen van een voltooide aanroep geeft het oorspronkelijk opgeslagen resultaat terug (geen heruitvoering).
• Dezelfde request_id die nog in behandeling is, geeft een succesresultaat terug met structuredContent.status = "processing".
• Dezelfde request_id met andere argumenten geeft een foutresultaat terug (isError: true) — gebruik een nieuwe request_id.

Sleutels worden ongeveer 24 uur bewaard. Een paar create-tools zijn expliciet niet-idempotent omdat de onderliggende POST een nieuw record aanmaakt (een reclaim zou het kunnen dupliceren): create_dns_zone, create_edge_rule, create_waf_custom_rule, create_rate_limit, create_access_list en activate_shield. Vermijd blinde retries op deze — gebruik de bijbehorende update_*-tool om een bestaand record te wijzigen. Elke tool adverteert zijn gedrag in tools/list via annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).

Tool-resultaten

Een succesvolle tools/call geeft zowel een tekstblok als gestructureerde data terug (dezelfde payload, gerenderd vanuit de REST API-templates zodat de shapes overeenkomen met de gedocumenteerde antwoorden):

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

Business-fouten zijn geen JSON-RPC-fouten — ze komen terug als een normaal resultaat met "isError": true en een tekstbericht. Secret-redactie wordt op beide emits toegepast: get_site bevat site.ssh alleen als de token ook sites:write heeft, en get_order strijkt altijd SSH-data weg.

Tool-catalogus

65 tools, alle gescoped tot het geautoriseerde account. Reads zijn breed; writes dekken DNS-records/-zones, site rename en restart, CDN-caching en cache purge, edge rules, en het volledige Shield-oppervlak (activate/deactivate, WAF-instellingen en managed/custom rules, rate limits, access lists, bot detection). Hieronder markeert * een vereist argument en markeert ✎ een write-tool (die een request_id vereist).

Sites

DNS

Domeinen en registratie

Registrar-writes (register/transfer, contact-CRUD, glue hosts) worden niet als tools blootgesteld — gebruik de REST API.

CDN, cache, logs en metrics

Site-gescoped. Reads gebruiken sites:read; writes gebruiken sites:write. CDN-reads en -writes hebben een geprovisionde pull zone nodig (anders cdn_not_active).

Edge rules

Site-gescoped, CDN actief. Reads gebruiken sites:read; writes gebruiken sites:write. Systeem (CPRESS -)-rules zijn verborgen en kunnen niet worden aangemaakt, bijgewerkt, verwijderd of getoggeld.

Shield

Site-gescoped. Reads gebruiken sites:read; writes gebruiken sites:write. Plan-gated (shield_not_in_plan); reads en writes hebben een geprovisionde shield-zone nodig (shield_not_active).

Orders en subscriptions

Alleen-lezen, scope billing:read.

Geavanceerd: handmatige installatie (stdio-bridge)

De mcp-remote-bridge draait lokaal over stdio en proxyt naar SuperSpace, waarbij hij de OAuth-login voor je afhandelt (hij opent een browser om te autoriseren en cachet daarna de token).

Bewerk het MCP-configuratiebestand van je client (bijvoorbeeld claude_desktop_config.json) en voeg SuperSpace toe onder het mcpServers-object:

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

Als npx niet op het PATH van de client staat — vaak het geval, omdat GUI-apps je shell-omgeving niet erven — en je mise hebt geïnstalleerd, gebruik die dan om npx te leveren:

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

Herstart vervolgens de client volledig. De eerste keer dat hij verbindt, opent er een browservenster zodat je kunt autoriseren via SuperSpace OAuth; keur het account goed en de verbinding is voltooid.