MCP (Model Context Protocol)

The whole API as a toolbox for AI agents — one tool per endpoint, the same rights as the access the agent signs in with.

What the server is

POST /api/mcp/v1 speaks MCP over Streamable HTTP (stateless). Every API endpoint is a tool named <domain>_<action> (e.g. contacts_list, invoices_issue); description and input schema come from the same source as this reference. Whatever the access may not do (scopes, clients-data enablement) does not appear in the tool list at all.

Connecting

Developer tools (Claude Code, Cursor, VS Code, n8n): server URL plus an Authorization header with an API key. Chat connectors (claude.ai, ChatGPT) that cannot set headers: enter only the URL — without a token the server answers 401 and points to the OAuth discovery via WWW-Authenticate; the client registers itself and obtains access through the 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"}'

Several organizations in the same tool

A chat connector keeps its connections by address, so the short address holds only ONE organization at a time. Every further one has its own address with the organization's identifier in it; you will find it ready to copy in the organization settings under “Access tokens”. The organization is then part of the address: the consent screen preselects it, and an access belonging to a different organization is rejected at that address. The short addresses stay valid.

http

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

Calling tools

Arguments are structured like the HTTP calls: params (path IDs), query (filters/cursor), body (payload). Write tools additionally take idempotencyKey. Responses are the endpoint’s JSON; errors come as Problem Details (RFC 9457) with 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…"
    }
  }
}

Compact: four tools for everything

At /api/mcp/v1/compact (and per organization /api/mcp/v1/compact/o/<orgId>) you find the same MCP with four tools instead of one per endpoint: guide (overview, an area or a guide), search_endpoints (search by words, in all languages), describe_endpoint (inputs as JSON Schema, scopes, example) and call_endpoint (call with the same scopes, limits and log). With all scopes the tool list of the full address is about 130,000 tokens; the compact one stays at a few thousand, and the assistant still sees the whole scope. Both addresses send an overview of claritos when connecting (areas, rules, flows). Sign-in and scopes as above.

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 for chat clients

Both MCP servers are protected resources per RFC 9728 — the API MCP (/api/mcp/v1, metadata at /.well-known/oauth-protected-resource/api/mcp/v1, all API scopes) and the website-builder MCP (/api/mcp, metadata at …/api/mcp, scopes sites:read and sites:write). The authorization server is claritos itself (“OAuth 2.1” guide). After consent the access applies to the chosen organisation. On the website-builder MCP scopes are enforced per tool: get_/list_/verify_/suggest_ read, everything else writes; a missing scope yields 403 insufficient_scope. Static cmcp_ tokens stay valid; API keys (capi_) deliberately do not work there. The tool list there also shows only what the access is allowed to do — an access with sites:read does not even see the writing tools.

Limits and log

Every tool call is an API call: rate limits (read/write bucket), idempotency, request log and alerts apply unchanged. Large lists are paginated (pass the cursor from the response).