MCP (Model Context Protocol)

Die ganze API als Werkzeugkasten für KI-Agenten — ein Werkzeug je Endpunkt, dieselben Rechte wie der Zugang, mit dem sich der Agent anmeldet.

Was der Server ist

POST /api/mcp/v1 spricht MCP über Streamable HTTP (zustandslos). Jeder API-Endpunkt ist ein Werkzeug mit dem Namen <domain>_<action> (z. B. contacts_list, invoices_issue); Beschreibung und Eingabeschema kommen aus derselben Quelle wie diese Referenz. Was der Zugang nicht darf (Scopes, Klientendaten-Freischaltung), erscheint gar nicht erst in der Werkzeugliste.

Verbinden

Entwickler-Werkzeuge (Claude Code, Cursor, VS Code, n8n): Server-URL plus Authorization-Header mit einem API-Schlüssel. Chat-Connectoren (claude.ai, ChatGPT), die keine Header setzen können: nur die URL eintragen — der Server antwortet ohne Token mit 401 und verweist per WWW-Authenticate auf die OAuth-Discovery; der Client registriert sich selbst und holt sich den Zugriff über den Consent.

json

{
  "mcpServers": {
    "claritos": {
      "url": "https://www.claritos.io/api/mcp/v1",
      "headers": { "Authorization": "Bearer capi_…" }
    }
  }
}

curl

curl -X POST https://www.claritos.io/api/mcp/v1 \
  -H "Authorization: Bearer capi_…" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Mehrere Organisationen im selben Werkzeug

Ein Chat-Connector führt seine Verbindungen nach Adresse — unter der kurzen Adresse ist deshalb nur EINE Organisation gleichzeitig verbunden. Für jede weitere gibt es eine eigene Adresse mit der Organisations-Kennung darin; du findest sie kopierfertig in den Organisations-Einstellungen unter „Zugangs-Token“. Die Organisation ist damit Teil der Adresse: die Zustimmungs-Seite wählt sie vor, und ein Zugang, der zu einer anderen Organisation gehört, wird an dieser Adresse abgewiesen. Die kurzen Adressen bleiben unverändert gültig.

http

POST https://www.claritos.io/api/mcp/v1/o/<orgId>
POST https://www.claritos.io/api/mcp/o/<orgId>

Werkzeuge aufrufen

Argumente sind gegliedert wie die HTTP-Aufrufe: params (Pfad-IDs), query (Filter/Cursor), body (Nutzlast). Schreibende Werkzeuge nehmen zusätzlich idempotencyKey. Antworten sind das JSON des Endpunkts; Fehler kommen als Problem-Details (RFC 9457) mit isError.

json

{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "contacts_create",
    "arguments": {
      "body": { "type": "PERSON", "firstName": "Anna", "lastName": "Muster", "email": "anna@example.com" },
      "idempotencyKey": "2f1c…"
    }
  }
}

Kompakt: vier Werkzeuge für alles

Unter /api/mcp/v1/compact (und je Organisation /api/mcp/v1/compact/o/<orgId>) liegt derselbe MCP mit vier Werkzeugen statt einem je Endpunkt: guide (Überblick, ein Bereich oder ein Leitfaden), search_endpoints (Suche nach Wörtern, in allen Sprachen), describe_endpoint (Eingaben als JSON-Schema, Rechte, Beispiel) und call_endpoint (Aufruf mit denselben Rechten, Limits und demselben Protokoll). Mit allen Rechten ist die Werkzeugliste der vollen Adresse rund 130.000 Token gross; die kompakte bleibt bei wenigen tausend, und der Assistent sieht trotzdem den ganzen Umfang. Beide Adressen schicken beim Verbinden einen Überblick über claritos mit (Bereiche, Regeln, Abläufe). Anmeldung und Rechte wie oben.

http

POST https://www.claritos.io/api/mcp/v1/compact
POST https://www.claritos.io/api/mcp/v1/compact/o/<orgId>

json

{ "name": "search_endpoints", "arguments": { "query": "finalize invoice" } }
{ "name": "describe_endpoint", "arguments": { "id": "invoices.issue" } }
{ "name": "call_endpoint", "arguments": { "id": "invoices.issue", "params": { "id": "inv_…" }, "idempotencyKey": "7a3e…" } }

OAuth für Chat-Clients

Beide MCP-Server sind geschützte Ressourcen nach RFC 9728 — der API-MCP (/api/mcp/v1, Metadaten unter /.well-known/oauth-protected-resource/api/mcp/v1, alle API-Scopes) und der Website-Builder-MCP (/api/mcp, Metadaten unter …/api/mcp, Scopes sites:read und sites:write). Der Authorization-Server ist claritos selbst (Leitfaden „OAuth 2.1“). Nach dem Consent gilt der Zugriff für die gewählte Organisation. Am Website-Builder-MCP werden die Scopes je Werkzeug durchgesetzt: get_/list_/verify_/suggest_ lesen, alles andere schreibt; fehlt der Scope, antwortet der Server mit 403 insufficient_scope. Statische cmcp_-Token bleiben gültig; API-Schlüssel (capi_) gelten dort bewusst nicht. Die Werkzeugliste zeigt dort ausserdem nur, was der Zugang darf — ein Zugang mit sites:read sieht die schreibenden Werkzeuge gar nicht erst.

Limits und Protokoll

Jeder Werkzeug-Aufruf ist ein API-Aufruf: Ratenlimits (Lese-/Schreibtopf), Idempotenz, Aufruf-Protokoll und Alarme gelten unverändert. Antworten großer Listen sind paginiert (Cursor in der Antwort weiterreichen).