Turn any Convex app into a remote MCP server with OAuth 2.1 auth built in, so users can connect Claude, ChatGPT, or Cursor to their data via tools you define.
npm install @convex-dev/mcpLet your users use your app from their AI agents. This component turns a Convex app into a remote MCP server with sign-in built in. Your users paste one URL into Claude, ChatGPT, Cursor or Claude Code, approve the agent on a page in your app, and the agent can then work with their data through tools you define.
Install @convex-dev/mcp, register the component in convex.config.ts, define an McpServer instance with your tools in convex/mcp.ts, and call mcp.registerRoutes(http) in your HTTP router. Your MCP server is then available at https://<deployment>.convex.site/mcp with OAuth 2.1 auth handled automatically.
The Convex MCP component implements a full OAuth 2.1 authorization server with PKCE, rotating refresh tokens, and device flow support. Users paste a single URL into their AI client, approve the connection on a consent page in your app, and the agent can then call tools that access their data through your Convex functions.
The @convex-dev/mcp component supports named scopes you define, such as read and write scopes, which users can grant selectively when approving an agent. Tool handlers receive a verified user object with userId, scopes, clientId, and connectionId, so you can enforce ownership checks inside your internal Convex functions the same way your UI does.
Export createApiKey from your McpServer instance via mcp.api() and call it from your settings UI. The key is returned once and can be passed as a bearer token header when adding the MCP server to a CLI agent like Claude Code using the --header flag.
The Convex MCP component supports MCP versions 2026-07-28, 2025-11-25, 2025-06-18, and 2025-03-26 on the same endpoint over Streamable HTTP. The latest version is stateless and includes server/discover support without requiring an initialize handshake.
No. The @convex-dev/mcp component includes a full OAuth 2.1 authorization server that runs inside your Convex deployment. It supports discovery per RFC 9728 and RFC 8414, dynamic client registration, PKCE, and rotating refresh tokens with replay detection. You provide a consent page in your frontend using your existing auth system such as Convex Auth, Clerk, or WorkOS.
Tool args and returns are defined using Convex validators from the convex/values package. The component converts these automatically to JSON Schema for the MCP inputSchema and outputSchema fields. If an agent passes arguments that do not match the schema, the error is returned to the model as a tool error it can self-correct, rather than throwing an unhandled exception.
Yes. An agent that can only make HTTP requests can fetch GET /mcp from the Convex MCP server and receives step-by-step instructions for signing in via the OAuth device flow (RFC 8628). The user gets a link to the consent page, approves the connection, and the agent receives a short-lived access token with no refresh token to avoid credentials appearing in chat transcripts.
Define named scopes on your McpServer instance, then assign each tool a scope property matching one of those keys. A connection only sees and can invoke tools within the scopes the user granted at approval time. Calling a tool outside granted scopes returns HTTP 403 with an insufficient_scope error. Users can also connect read-only agents by granting only read scopes.