MCP server endpoint

Cantinarr exposes its tools as a Model Context Protocol server at /mcp (Streamable HTTP, session tracked via Mcp-Session-Id). External clients (Claude Desktop, Claude Code, Codex, …) discover auth from the well-known metadata, register dynamically, and log in through a browser page: with a Cantinarr password or a passkey. This browser login grants an external client access to Cantinarr; it is unrelated to the AI Access device-code flows that grant Cantinarr outbound OpenAI OAuth access to a personal or admin-shared ChatGPT account. Connect-link-only users can create their first passkey from the MCP login flow; a password is what authorizes MCP on plain-HTTP deployments where WebAuthn is unavailable. Initialization reports the running Cantinarr build version, advertises only the implemented tool/resource/prompt behavior, and tells clients where to load the operating guide.

Access tokens are short-lived and audience-bound to /mcp. Refresh tokens are persisted, rotate on use, have a one-year sliding lifetime, and are tied to a Cantinarr device record: revoking the device revokes the MCP client. Registered clients and token state live in the database, so they survive restarts and upgrades.

The MCP server also publishes prompt templates and a guide://cantinarr/agent-guide.md resource so external agents pick up the same operating habits as the built-in assistant (trending behavior, display_media carousel use, request-status checks before requests, admin download-triage rules). Tool declarations include human-readable titles and explicit read-only, destructive, idempotency, and open-world hints. Media-capable tools reference the ui://cantinarr/media-results.html MCP App; its resource declaration and returned content both carry the image-domain CSP metadata enforced by compliant hosts.

Authenticated MCP request observability records only bounded protocol metadata: JSON-RPC method and safe target name, protocol/lifecycle era, whether client capabilities were supplied, sanitized client name/version, HTTP status, classified outcome, and duration. Authentication and permission checks run before any observation body read. Logs never contain bearer or session tokens, tool arguments or results, capability values, resource URIs, or JSON-RPC error text. This makes discovery failures and legacy fallback sequences diagnosable without turning protocol logs into a content audit trail.

Client example:

{
  "mcpServers": {
    "cantinarr": { "url": "http://your-server:8585/mcp" }
  }
}

View the maintained source for this page.