用途：把 Convex 函数暴露成 Claude、ChatGPT 等 MCP 客户端可调用的工具，并以已登录用户身份执行。服务器托管在 Convex 内，基于 convex-mcp-gateway 组件，以 Convex httpAction 承载 MCP 服务器，处理 JSON-RPC/Streamable-HTTP 协议、OAuth 发现文档与审计日志，一套服务器可服务所有 MCP 客户端，无需独立 Web 服务器、桥接或密钥对。
主要构成：Tools 用 defineMcpQuery / defineMcpMutation / defineMcpAction 把 Convex 函数映射为工具，身份相关工具需传注入的 caller 参数（identityArg），因为 Convex 在组件边界会剥离 ctx.auth，因此按 caller.subject 而非 ctx.auth 限定身份。Identity 用 resolveIdentity 在 Clerk 的 OIDC userinfo 端点校验不透明 OAuth access token，返回 { subject, claims }；Clerk 作为 OAuth 授权服务器（支持动态客户端注册），网关为资源服务器。Mount 在 convex/http.ts 中用一个 httpAction 调用 gateway.handleMcpRequest(...)，并加上受保护资源发现路由。
使用方式：npm install convex-mcp-gateway，在 convex/convex.config.ts 中 app.use(mcpGateway)；将 references/mcp.ts、references/mcp-tools.ts、references/http.ts 分别复制到 convex/mcp.ts、convex/mcpTools.ts、convex/http.ts，替换示例工具并保持 authorize、resolveClerkIdentity、initializeInstructions；工具实现用 internalQuery/internalMutation/internalAction 并按 caller.subject 限定归属。设置 MCP_AUTH_SERVER_URL（Clerk issuer）或复用 CLERK_JWT_ISSUER_DOMAIN；在 Clerk 后台启用动态客户端注册，关闭“access tokens as JWTs”。执行 npx convex deploy 后，在 Claude/ChatGPT 中以 https://<deployment>.convex.site/mcp 添加连接器。
适用与限制：适合用 Convex + Clerk、希望 AI 客户端以真实用户身份操作应用的场景；不适用于本地 stdio MCP 服务器（无需 OAuth）、非 Convex+Clerk 应用，以及无需用户身份的只读公开数据。常见错误包括在工具里读 ctx.auth（恒为空）、把工具函数暴露为公开 api.*、未启用或未保存 Clerk 动态客户端注册、漏设 requireAuth: true、CORS 未暴露 mcp-session-id / www-authenticate、caller.subject 与用户索引键不匹配、工具描述过弱。更多细节见 references/setup-and-gotchas.md。