convex-mcp-gateway weekly downloads statistics

convex-mcp-gateway

Auth-aware MCP server for Convex. Expose selected Convex functions as MCP tools, bring your own JWT issuer, declare scopes/roles per tool, get an audit log and OAuth 2.1 protected-resource discovery for free.

Built as a Convex Component.

<!-- START: Include on https://convex.dev/components -->

Features

• Type-safe tool registration: defineMcpQuery / defineMcpMutation / defineMcpAction declare a Convex function as an MCP tool with end-to- end-typed args and (optional) returns validators. Declare the list once and pass it as tools to handleMcpRequest, the registry auto-syncs on connect (no separate registration mutation), or call gateway.register(...) for imperative/dynamic catalogs
• MCP dual-era Streamable HTTP: legacy 2025-03-26/2025-06-18/2025-11-25 sessions remain supported alongside stateless 2026-07-28 requests, discovery, routing-header validation, and private cache hints. A client requesting an unknown revision negotiates down to 2025-11-25 (what the current official TypeScript SDK pins as latest); all three legacy revisions share one transport wire contract (2025-11-25's SSE resumability framing needs an event store the gateway doesn't have, so it isn't emitted, a deliberate SHOULD deviation)
• Stateless multi-round trips: declarative stateless-era tools use a host-side beforeCall hook to request input before any Convex function runs, then receive HMAC-verified continuation state plus an idempotency key on retry; resources/read gets the same treatment through beforeResourceRead, so a read can ask a question before serving content. See Multi-round-trip requests and Resources
• MCP Tasks (poll-first): opt-in io.modelcontextprotocol/tasks support; task-augmented tools/call returns a handle, clients poll tasks/get, owner-bound with TTL retention and lifecycle audit. Built-in durable executor via the Convex scheduler, or bring @convex-dev/workflow for retries and input_required rounds. See Tasks
• MCP resources: defineMcpResource / defineMcpResourceTemplate serve resources/list, resources/read, and resources/templates/list (RFC 6570). Central authorizeResource hook, opt-in resource audit, runtime shape validation, opt-in resources/subscribe capability, and opt-in anonymous access for public content. See Resources & templates
• MCP prompts: defineMcpPrompt serves prompts/list and prompts/get, with argument checks, result validation, an authorizePrompt hook, and opt-in anonymous access. See Prompts
• One authorize callback: gates tools/call and filters tools/list with mode: "list" | "call"; uses your existing ctx.auth.getUserIdentity()
• OAuth 2.1 protected-resource discovery: RFC 9728 metadata, RFC 6750 WWW-Authenticate headers, multi-tenant ready
• Optional OAuth bridge: RFC 8414 AS metadata wrap + RFC 7591 DCR for browser MCP clients (claude.ai) against IdPs without DCR support, with opt-in CIMD advertisement when the upstream authorization server supports it
• requireAuth for all-private servers: opt-in 401-challenge on anonymous requests so browser clients (claude.ai) begin the OAuth flow instead of seeing an empty tools/list and never prompting a login
• initializeInstructions: optional server-level guidance returned in the MCP initialize result's instructions field, surfaced to the LLM without bloating individual tool descriptions
• Audit log: one row per call with per-tool argument redaction (verbatim / dropped / dotted-path redacted)
• Wire-error sanitization: generic message on the wire, full detail in audit; ConvexError passes through for deliberate user-facing messages
• convex-test helper: convex-mcp-gateway/test exports a one-line register(t) that hooks the component into a convexTest instance so your host tests can exercise the full /mcp/ round-trip in-process. See Testing

What it does

You mount the gateway in a single httpAction and pass an authorize JS callback that decides per call whether the request goes through. The gateway handles the JSON-RPC envelope, legacy Streamable-HTTP session lifecycle, stateless 2026-07-28 requests, the OAuth discovery doc, the WWW-Authenticate headers, and the audit log. Your existing Convex auth (Clerk, Auth0, Pocket-ID, custom JWT issuer) just works.

A standalone editorial-styled version of the diagram is at docs/diagrams/architecture.html; in-depth sequence and data-flow diagrams live in docs/architecture.md.

Try it

The companion repo convex-mcp-gateway-demo is a notes app that registers five tools (public, identity-gated, role-gated) and shows the audit log live. Three run modes including a local-backend setup that needs no Convex account:…