Cairnloop.Web.MCP.Router (cairnloop v0.5.1)

Copy Markdown View Source

Optional read-only MCP seam for Cairnloop-governed tools.

Handles JSON-RPC 2.0 POST requests per MCP spec 2025-11-05:

  • initialize — capability negotiation; returns protocolVersion and capabilities.tools
  • tools/list — projects all configured governed tools through ToolProjector.spec_to_mcp/1
  • All other methods — returns JSON-RPC error -32601 Method not found (HTTP 200)

Host integration

Mount this Plug via forward in the host's Phoenix router:

forward "/mcp", Cairnloop.Web.MCP.Router

The host SHOULD add authentication middleware before the forward — Cairnloop does not prescribe an auth mechanism (D17-09).

JSON-RPC 2.0 semantics

Per the JSON-RPC 2.0 spec, error responses carry HTTP status 200 — error information is in the response body's error field, not the HTTP status code (Pitfall 3 from RESEARCH.md).

Security

The method field from incoming JSON-RPC requests is NEVER converted to an atom — all dispatch uses string case pattern matching to prevent atom exhaustion (T-17-02-01, D-19 security posture).

Write actions (tools/call) are permitted for authenticated clients but are strictly routed through Cairnloop.Governance.propose/3. No direct tool execution occurs.