Developer

MCP for AI assistants

Sanshain exposes its catalog to AI assistants over the Model Context Protocol. An assistant with the endpoint configured answers "who provides the orders API and who depends on it?", "where is the endpoint that creates an invoice?", "what changed in payments between 2.3.0 and 2.4.0?" or "show me the spec of inventory" straight from the catalog. Read-only, and only the catalog: never users, roles, settings, authentication, audit or observability data.

In short#

• Endpoint: POST /mcp, Streamable HTTP, stateless.
• Auth: Authorization: Bearer <API token>. Sessions are refused. Mint a read-only token.
• Tools: list_services, describe_service, find_endpoint, get_spec, get_graph, diff_versions, blame, endpoint_structure.
• Limits: 60 tool calls per minute per token, 64 KiB per answer; larger answers come back as a summary with a hint.
• Off switch: MCP_ENABLED=false leaves /mcp unmounted.

The token#

The endpoint authenticates with API tokens, the same tokens CI uses, and nothing else. Create one on /account.html and tick Read-only (for AI / MCP clients): a read_only token can query everything the tools answer but is refused on every route that changes the catalog (provide, retire, require, catalog push), so a misdirected assistant cannot publish or pin anything. A full token works too; prefer read-only unless the same token also drives a build. The token list on the account page shows when an assistant last used its token.

The endpoint#

/mcp speaks MCP's Streamable HTTP transport in stateless mode: every request carries the token, no session is kept, and a restart loses nothing a client could notice. JSON-RPC requests are POSTed with Accept: application/json, text/event-stream; the route also answers GET and DELETE as the transport requires.

Developer mode substitutes the dev user when no header is sent, exactly as the API does. Local only.

Client configuration#

Claude Code

claude mcp add --transport http sanshain https://<host>/mcp --header "Authorization: Bearer <token>"

Any stdio-only client, through the mcp-remote bridge:

{
  "mcpServers": {
    "sanshain": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<host>/mcp", "--header", "Authorization: Bearer <token>"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "sanshain": {
      "url": "https://<host>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

VS Code (.vscode/mcp.json) spells the top-level key servers and the transport "type": "http":

{
  "servers": {
    "sanshain": {
      "type": "http",
      "url": "https://<host>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Keep the token out of files you commit; most clients read it from an environment variable (${env:SANSHAIN_TOKEN} in VS Code, ${SANSHAIN_TOKEN} in Cursor).

The tools#

Every tool answers compact JSON stamped with the scope (and at) it was computed for. Scopes are the reports': dev (default) is everything ever provided or required, main is what trunk builds currently pin, and a sanshain-branch name is a release cut; main and branches take an at instant on get_graph. Unknown names are refused with a message, never with a transport error.

api_type is openapi, asyncapi or proto; versions are MAJOR.MINOR.PATCH; path and method always go together. Every schema refuses unknown parameters.

Over-budget answers#

An answer above MCP_MAX_RESULT_BYTES is never truncated silently:

• get_spec answers {summary: {lines, bytes, endpoints: [...]}, hint: "use offset/limit (line numbers) or path+method"};
• get_graph answers the node counts per kind and the edge count, with a hint to narrow with service or api_type;
• diff_versions answers the added and removed counts with a hint to narrow with path and method;
• blame answers the blocks without their lines (line_count instead);
• endpoint_structure answers the tree two levels deep, cut nodes marked children_omitted;
• list_services, describe_service and find_endpoint answer counts and a hint.

Limits and settings#

initialize and tools/list do not count against the rate limit; only tool calls do. The HTTP body limit (MAX_SPEC_BODY_BYTES) applies to requests as everywhere else. Two Prometheus counters on /metrics describe the traffic: sanshain_mcp_tool_calls_total{tool, outcome} with outcome one of ok, error, rate_limited, over_budget, and sanshain_mcp_result_bytes_total{tool}.

Security notes#

• Only API tokens are accepted, so there is no ambient credential a browser could ride; the endpoint is outside CSRF protection for that reason.
• Host-header validation is disabled on the transport: Sanshain is reached under whatever name the deployment gave it, and the bearer token, not the Host header, keeps a DNS-rebinding attacker out.
• A token's last_used_at on the account page shows when an assistant last used it.

Checked against v2.6.0.