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

Copy Markdown View Source

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

Handles JSON-RPC 2.0 POST requests per MCP spec 2025-03-26:

  • 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). This Plug handles discovery only; no tool execution path is reachable (D17-06).

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). No Ecto queries, no propose/3, no run/3 are reachable from this Plug.