Convex MCP Gateway

Auth-aware MCP server for Convex that exposes functions as MCP tools with OAuth 2.1 discovery, per-tool scopes, and audit logging.

Installation

npm install convex-mcp-gateway

About Convex MCP Gateway

An auth-aware MCP (Model Context Protocol) server component that exposes Convex functions as MCP tools for AI agents. Provides OAuth 2.1 protected-resource discovery, per-tool authorization with scopes/roles, comprehensive audit logging, and wire-error sanitization. Built as a Convex Component with type-safe tool registration and full integration with Convex's existing auth system.

Benefits

Expose Convex functions as type-safe MCP tools with end-to-end validation
Integrate existing Convex auth (Clerk, Auth0, custom JWT) without code changes
Get OAuth 2.1 protected-resource discovery and audit logging automatically
Control access per tool with a single authorize callback and scope filtering

Use cases

how to expose Convex functions to AI agents

Use convex-mcp-gateway to register Convex queries, mutations, and actions as MCP tools with defineMcpQuery, defineMcpMutation, and defineMcpAction. The component handles the MCP protocol, session management, and tool discovery so AI agents can call your Convex functions directly.

MCP server with authentication and authorization

Convex MCP Gateway provides built-in auth integration with your existing Convex auth setup. Configure a single authorize callback to control access per tool, with automatic OAuth 2.1 discovery and WWW-Authenticate headers for spec-compliant MCP clients.

audit logging for AI agent tool calls

The component automatically logs every MCP tool call with argument redaction options (verbatim, dropped, or dotted-path redacted). Audit entries include caller identity, tool name, arguments, results, and timing for compliance and debugging.

Frequently asked questions

Does convex-mcp-gateway work with existing Convex auth providers?

Yes, convex-mcp-gateway integrates with any OAuth 2.1/OIDC provider that Convex supports including Clerk, Auth0, Pocket-ID, AWS Cognito, and custom JWT issuers. It uses your existing ctx.auth.getUserIdentity() without requiring code changes to your auth setup.

How do I control which tools are visible to different users?

Configure a single authorize callback that receives toolMetadata and decides access per call. The same callback filters tools/list (what users see) and tools/call (what they can execute) using a mode parameter. You can implement role-based or scope-based access control in this callback.

What MCP protocol features does the gateway support?

Convex MCP Gateway implements MCP 2025-06-18 Streamable HTTP with sessions, Accept negotiation, MCP-Protocol-Version validation, and identity-bound DELETE operations. It handles the full JSON-RPC envelope and session lifecycle automatically.

Can I use this with browser-based MCP clients like claude.ai?

Yes, convex-mcp-gateway includes an optional OAuth bridge mode that provides RFC 7591 Dynamic Client Registration for browser MCP clients when your IdP doesn't support DCR natively. This enables integration with claude.ai and other browser-based MCP clients.