# MCP Server Application MCP server implementation - Package: @bijectionhq/mcp - Category: AI & Agents - Status: Included - License: Apache-2.0 - Bijection source (repository access required): https://github.com/bijectionhq/mcp/tree/e463894c4c6b158fbf1a9953c711f7278d2075f9 - Upstream: https://github.com/convex/mcp/tree/d8db15c0775c656d8585006955b079b408688b09 - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/mcp ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/mcp.git cd mcp git checkout e463894c4c6b158fbf1a9953c711f7278d2075f9 ``` ## Before using this component Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This source is included in Bijection's workspace. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute. ## Upstream package documentation Recorded 2026-10-23. This describes @convex-dev/mcp; check the Bijection adaptation separately. Convex MCP turns a Convex app into a remote MCP server with OAuth 2.1 authorization built in. Developers define tools using Convex validators, register HTTP routes, and add a consent page; users then paste one URL into Claude, ChatGPT, Cursor, or Claude Code to connect their AI agent to their own data. The component handles the full OAuth 2.1 flow including PKCE, rotating refresh tokens, dynamic client registration, and a device flow for agents that start from a pasted URL, all running inside the Convex deployment with no separate auth provider. ### Use cases - You want to let users connect their Claude or Cursor agent to your app so the agent can read and write their data through tools you control - You are building a SaaS product and need users to authorize third-party AI agents against their accounts using a standards-compliant OAuth 2.1 flow without standing up a separate auth server - You want to expose scoped read-only or read-write tool sets so users can grant minimal permissions to an agent from a settings page - You need CLI or headless agent support and want to issue API key bearer tokens that agents can use with standard MCP clients like claude mcp add - You want an audit-ready MCP integration where tokens are stored hashed, expired credentials are cleaned up by a cron, and unauthenticated endpoints are rate limited ### How it works Define an `McpServer` instance in `convex/mcp.ts`, passing tool definitions built with the `tool` helper. Each tool declares Convex validator schemas for `args` and `returns`, which are converted to JSON Schema for MCP clients. Tool handlers receive a verified `user` object containing `userId`, `scopes`, `clientId`, and `connectionId`, and should delegate to internal Convex queries or mutations that enforce ownership the same way the app UI does. Register routes by calling `mcp.registerRoutes(http)` in `convex/http.ts`. This mounts the MCP endpoint at `/mcp`, plus OAuth 2.1 discovery documents at `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`. The component speaks MCP protocol versions 2026-07-28, 2025-11-25, 2025-06-18, and 2025-03-26 over Streamable HTTP on the same endpoint. Export `getAuthRequest` and `authorize` from the `mcp.api({ getUserId })` call and wire them into a consent page at `consentUrl`. When an agent connects, the user lands on that page, sees which scopes are requested, and approves or denies. For the device flow, where an agent fetches `GET /mcp` and receives instructions, the consent page must also display and validate a `userCode` before calling `authorize`. Users can later list connected agents and revoke them via `listConnections` and `revokeConnection`, and create bearer-token API keys via `createApiKey`. ### Upstream README Let your users use your app from their AI agents. This component turns a Convex app into a remote [MCP](https://modelcontextprotocol.io) 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. ```ts export const mcp = new McpServer(components.mcp, { name: "todos", version: "1.0.0", consentUrl: `${process.env.SITE_URL}/connect`, tools: { add_todo: tool({ description: "Add a todo for the user.", args: { text: v.string() }, handler: (ctx, args, user) => ctx.runMutation(internal.todos.add, { userId: user.userId, ...args }), }), }, }); ``` - **Tools from Convex validators.** `args` and `returns` become JSON Schema (`inputSchema` / `outputSchema`). Bad arguments go back to the model as tool errors it can fix. - **A full OAuth 2.1 authorization server.** It supports discovery (RFC 9728 / RFC 8414), dynamic client registration, PKCE, rotating refresh tokens with replay detection, and audience-bound tokens. It works with claude.ai connectors and any spec-compliant client. Client ID metadata documents are available as an opt-in for hosts you allowlist. - **Paste the URL into any agent chat.** An agent that can only make HTTP requests fetches `/mcp` and gets instructions. It then shows the user a clickable approval link, gets a short-lived token, and starts calling tools. No MCP client setup is needed. This uses the OAuth device flow, RFC 8628. - **Your auth, your consent page.** Users sign in with whatever your app already uses (Convex Auth, Clerk, WorkOS, …), then approve the agent. - **Connections UI.** Users can list connected agents, disconnect them, and create API keys for CLI agents. - **Scopes.** You can let users connect a read-only agent. - **Secrets are stored hashed.** Tokens are opaque and stored as SHA-256 only. Expired credentials and unused client registrations are cleaned up by a cron, and the unauthenticated endpoints are rate limited. Speaks MCP **2026-07-28** (stateless, with `server/discover`, no `initialize`) and the earlier 2025-11-25, 2025-06-18 and 2025-03-26 versions on the same endpoint, over Streamable HTTP. Everything runs inside your Convex deployment: no separate server or auth provider. Found a bug? Feature request? [File it here](https://github.com/get-convex/mcp/issues). ## Quick start: paste this into your coding agent Open your Convex app in Claude Code, Codex, Cursor or any coding agent and paste: ```text Add an MCP server to this Convex app so our users can use it from their AI agents (Claude, ChatGPT, Cursor, Claude Code). 1. Add `@convex-dev/mcp@alpha` with this project's package manager (npm, pnpm, yarn or bun — match the lockfile). 2. Read node_modules/@convex-dev/mcp/skills/convex-mcp/SKILL.md and its references, and follow it: study the app, then propose the MCP tools (names, descriptions, args, scopes, annotations) as a table and wait for my OK before writing code. 3. Wire it up as the skill describes: convex.config.ts, convex/mcp.ts with the tools on internal functions that take the verified userId, http.ts, a /connect consent page using our existing sign-in, and a "Connected agents" section in settings with API keys. 4. Verify against the dev deployment: create an API key, run tools/list, and call every tool once. 5. Then read node_modules/@convex-dev/mcp/skills/convex-mcp-security/SKILL.md and run that audit with two test users. Fix what it finds and show me the report. Don't deploy to production or touch real user data. ``` The agent will stop after step 2 to show you the proposed tools. Already have an MCP server built with this component? Paste this to audit it: ```text Read node_modules/@convex-dev/mcp/skills/convex-mcp-security/SKILL.md and audit this app's MCP server as it describes, against our dev deployment with two test users (mint keys with createApiKeyForUser if we export it). Prove each finding, fix it, re-prove it, and show me the report. Don't touch production or real user data. ``` ## Installation ```sh npm install @convex-dev/mcp@alpha # or pnpm add / yarn add / bun add ``` ```ts // convex/convex.config.ts import { defineApp } from "convex/server"; import mcp from "@convex-dev/mcp/convex.config.js"; const app = defineApp(); app.use(mcp); export default app; ``` > The MCP and OAuth discovery routes are served from your app's HTTP router > at the origin root (`/.well-known/...`). Don't give the app itself an > `httpPrefix`. ## Usage ### 1. Define the server and tools Tool handlers run in an HTTP action. There's no `ctx.auth` identity there: the verified user comes in as `user.userId`. Pass it to internal functions, and check ownership there just like your UI code does. ```ts // convex/mcp.ts import { McpServer, tool } from "@convex-dev/mcp"; // Convex Auth 0.0.x; with Convex Auth v2 import from "@convex-dev/auth/core". import { getAuthUserId } from "@convex-dev/auth/server"; import { v } from "convex/values"; import { components, internal } from "./_generated/api"; import type { Id } from "./_generated/dataModel"; export const mcp = new McpServer(components.mcp, { name: "todos", title: "Todos", version: "1.0.0", instructions: "Manage the user's todo list.", // Your frontend's consent page. Set it explicitly. consentUrl: process.env.MCP_CONSENT_URL!, scopes: { "todos:read": "See your todos", "todos:write": "Add and complete your todos", }, tools: { list_todos: tool({ description: "List the user's todos, optionally filtered by completion.", args: { done: v.optional(v.boolean()) }, returns: v.object({ todos: v.array(v.object({ id: v.string(), text: v.string(), done: v.boolean() })), }), annotations: { readOnlyHint: true }, scope: "todos:read", handler: async (ctx, args, user) => ({ todos: await ctx.runQuery(internal.todos.listForUser, { userId: user.userId as Id<"users">, ...args, }), }), }), }, }); // Functions your frontend uses for the consent page and settings. export const { getAuthRequest, authorize, listConnections, revokeConnection, createApiKey, } = mcp.api({ getUserId: getAuthUserId }); ``` For the CLI and tests, also export the internal helpers. They can only be called with deploy credentials: ```ts export const { createApiKeyForUser } = mcp.internalApi(); // npx convex run mcp:createApiKeyForUser '{"userId":""}' ``` To type `user.userId` as your own ID type, use `createTool>()` in place of `tool`. Then annotate the server's type, which breaks a TypeScript inference cycle when the same file exports functions: ```ts const tool = createTool>(); export const mcp: McpServer> = new McpServer(components.mcp, { ... }); ``` `getUserId` decides who a connection acts for. Return a stable ID that can't collide across identity providers, such as your users table ID or `identity.tokenIdentifier`. ### 2. Register the routes ```ts // convex/http.ts import { httpRouter } from "convex/server"; import { mcp } from "./mcp"; const http = httpRouter(); mcp.registerRoutes(http); export default http; ``` Your MCP server URL is `https://.convex.site/mcp`. Two URLs are easy to confuse: - `consentUrl` is the page on your **frontend** where users approve agents. - `siteUrl` is the public origin of your **Convex HTTP actions**, which is the server URL users paste. It defaults to `CONVEX_SITE_URL`. Pass it if you use a custom domain for HTTP actions. Every authorization creates its own connection, so a user can connect the same agent on several machines. ### 3. Add a consent page When an agent connects, the user is sent to `consentUrl?request=`. On that page, make sure the user is signed in (coming back to the same URL afterwards), show who's asking, and let them decide. Don't let it be framed: send `Content-Security-Policy: frame-ancestors 'none'` where your host can. On static hosts that can't set headers, refuse to render the approval UI when `window.top !== window.self`. The example does both. ```tsx const requestId = new URLSearchParams(location.search).get("request")!; const request = useQuery(api.mcp.getAuthRequest, { requestId }); const authorize = useAction(api.mcp.authorize); // request: { clientName, redirectUri, scopes: [{ name, description }], status } const decide = async (approve: boolean) => { const { redirectUrl } = await authorize({ requestId, approve }); window.location.assign(redirectUrl); // back to the agent }; ``` #### Agents that started from a pasted URL (device flow) An agent with only an HTTP tool can fetch `GET /mcp`, which returns step-by-step instructions, and sign in with the device flow, using the public client ID `mcp-agent`. The user gets a link to your consent page, `consentUrl?request=…`. For these requests, `getAuthRequest` returns `kind: "device"` and a `userCode`. Your consent page should: - show the `userCode` and **require** the user to confirm it matches what their agent shows (a checkbox) before enabling Allow, then pass it to `authorize({ requestId, approve: true, userCode })`. The server refuses device approvals without the matching code, so a consent page that skips this step fails safely instead of becoming a phishing hole; - label `clientName` as unverified, since the agent reports it about itself; - after `authorize`, which returns `redirectUrl: null` for device requests, tell the user to go back to their agent; - if opened without `?request=`, offer a box to type the code, which calls `findAuthRequest({ userCode })`. That lookup is rate-limited per user. Device-flow tokens are short-lived access tokens with **no refresh token**, since they may end up in chat transcripts. The tool list isn't shown on the public guide unless you set `describeTools: true`. Set `deviceFlow: false` to turn the feature off. The example consent page ([`example/src/App.tsx`](./example/src/App.tsx)) implements all of this. ### 4. Show connected agents Settings can use `listConnections`, `revokeConnection({ id })` and `createApiKey({ name })`. The API key is returned once. CLI agents use it as a bearer token: ```sh claude mcp add --transport http todos https://.convex.site/mcp \ --header "Authorization: Bearer " ``` See [`example/`](./example) for a complete app with a consent page and a connections UI. ### Tool results - **Return values.** A string becomes text content. Any other value becomes JSON text content, plus `structuredContent` when `returns` is set and the value is an object. `bigint` values are encoded as strings and bytes as base64. - **`returns` is enforced.** A result that doesn't match it, including one with extra fields, is logged and becomes a generic tool error. Nothing you didn't declare reaches the agent. - **Full control.** Return `callToolResult({ content: [...], isError })` to shape the result yourself, for example to return images. - **Errors.** Throw `ConvexError("…")` to send the model a message it can act on. Other errors are logged, and the model gets a generic failure. ### Scopes Give a tool `scope: "x"` (it must be a key of `scopes`). A connection only sees and can call tools in its granted scopes. A call outside those scopes gets HTTP 403 `insufficient_scope`. When a client requests no scope, the connection gets all of them. ## Authorization The component authenticates the connection and gives your tool the verified `user` (`userId`, plus the connection's `scopes`, `clientId` and `connectionId`). **Deciding what that user may do is your app's job.** Do it the same way your UI does, inside the transaction that reads or writes: 1. **Use one access helper for the UI and for MCP.** Put the check in a function like `requireList(ctx, actor, listId, "view" | "edit" | "manage")`. Call it from your UI mutations *and* from the internal functions your tools call, so the two paths can't drift apart. Return the same error for "not found" and "not allowed". 2. **Pass the whole MCP user, not just the ID.** Internal functions take `{ user: vMcpUser(v.id("users")) }`. Your helper can then let a connection's scopes **narrow** what the user may do. For example, a `todos:read` connection acts as a viewer even on the user's own list. 3. **Plug in whatever already decides access in your app:** - **Your own tables**, such as owners, members and roles. The example ([`example/convex/access.ts`](./example/convex/access.ts)) shares lists with viewer and editor roles. - **A sharing or authorization component.** Call its transactional check, such as `requireAccess(ctx, { resourceRef, actor }, "edit")`, from your helper. - **An external engine** (OpenFGA, Cerbos, WorkOS FGA). These can't be called from a query or mutation, which can't make network requests. Copy the relationships you need into indexed Convex tables, check those inside the transaction, and keep them in sync from actions or webhooks. Calling the engine from an action and then writing in a separate mutation leaves a gap between the check and the write. Only do that if a short delay in revocation is acceptable. 4. **Lists and searches** should query what the user can reach (owned plus shared, through an index), not fetch everything and then filter. ## Security checklist Before you ship, make sure that: - [ ] **Tools act only as `user.userId`.** No tool argument decides whose data is touched. - [ ] **The functions tools call are `internal*`.** A public function that trusts a `userId` argument can be called by anyone. - [ ] **Every ID from the model is checked for access** with the same helper your UI uses, including IDs of child objects. - [ ] **Every tool that returns an object declares `returns`.** It's enforced, so it is also the allowlist of fields that reach the agent. - [ ] **Reads and writes have separate scopes,** and every tool is annotated (`readOnlyHint`, `destructiveHint`, `openWorldHint`). - [ ] **Tools that send data out are behind a server-side policy,** such as a recipient allowlist or confirmation in your app, if your server also returns text written by other people. Annotations don't stop prompt injection. - [ ] **The consent page can't be framed** (with a `frame-ancestors` header, or the in-page check on static hosts) and labels client names as unverified. - [ ] **For device-flow requests, the consent page shows the user code** and requires the user to confirm it matches, before Allow is enabled. - [ ] **`expect(mcp.lint()).toEqual([])` passes in a test.** `lint()` flags missing scopes, missing annotations and inconsistent scopes. It also logs once, on the first MCP request, unless you set `warnings: false`. Then run the security audit skill (prompt above), which proves each item live with two users. ## Designing your tools This package ships two agent skills: - `skills/convex-mcp` reads your app and proposes a task-shaped tool surface (names, descriptions, args, scopes, annotations) before wiring it up. - `skills/convex-mcp-security` audits an app's MCP server — identity, cross-user access, public functions taking `userId`, data in results, prompt-injection and exfiltration paths, the consent page — proving each finding with two real users. ```sh npx skills add get-convex/mcp ``` ## Testing ```ts import { convexTest } from "convex-test"; import mcpTest from "@convex-dev/mcp/test"; const t = convexTest(schema, modules); mcpTest.register(t); // or mcpTest.register(t, "myMcp") for a custom name const res = await t.fetch("/mcp", { method: "POST", headers: { Authorization: `Bearer ${apiKey}` }, body }); ``` `register` also registers the bundled rate limiter. Set `process.env.CONVEX_SITE_URL` in tests. See `example/convex/mcp.test.ts`. ## Limits and roadmap - **Short tool calls.** Each tool call is a single HTTP action, so it has Convex's action time and memory limits. Keep calls short and return small results. - **Device flow and the pasted-URL guide** are on by default. Turn them off with `deviceFlow: false`. - **Not yet supported:** server-to-client streaming (SSE progress, sampling, elicitation), resources and prompts, and confidential clients. - **Rate limiting.** Client registration and `/authorize` are rate limited through a bundled `@convex-dev/rate-limiter` instance. Limits are global or per client, not per IP. The MCP endpoint itself isn't rate limited yet. - **Client ID metadata documents** are fetched from your backend, so they only work for hosts you list in `clientMetadataDocumentHosts`.