Convex 是一个响应式后端平台，为开发者提供数据库、函数、工作流、同步、搜索、文件存储等能力，全部基于 TypeScript，无需编写胶水代码。Convex 1.19.5 版本引入 beta 版 MCP 服务器，用于让 AI 智能体内省部署状态、运行函数、读写数据。
用途
Convex MCP 服务器主要面向 AI 智能体，使其能够与 Convex 部署进行交互。MCP（Model Context Protocol）是一种标准化协议，用于 AI 智能体与不同工具之间的交互，例如读取本地文件系统、搜索网络或控制浏览器。Convex 的 MCP 服务器支持内省部署的表和函数、调用函数、读写数据，并允许智能体编写一次性查询代码，由于 Convex 查询完全沙箱化且不能写入数据库，因此可以安全地让智能体自由操作。
主要能力
- 状态查询：status 工具让模型查询其可访问的部署，并返回一个“部署选择器”，可传递给后续工具调用。每个部署到 Convex 的应用对应一个项目，项目可有多个部署：一个生产部署、每个团队成员一个开发部署，以及可能的多个预览部署。
- 表列表：tables 工具列出部署的所有表，返回表名、声明的模式（如有）和推断的模式。Convex 自动跟踪数据形状，即使未声明模式，智能体也可据此建议模式改进，例如填充 v.any() 类型或发现未使用的可选字段。
- 数据分页：data 工具用于分页浏览表中的文档。
- 一次性查询：runOneoffQuery 工具允许模型编写代码查询部署数据。代码完全沙箱化且不能修改数据库，因此无危害。示例：编写一次性查询，找出聊天应用消息中出现频率最高的词。
- 函数规格：functionSpec 工具让模型查看所有已部署函数及其类型和可见性。相比阅读 convex/ 目录下的所有代码，单次工具调用获取 API 更高效。
- 运行函数：run 工具用于实际运行函数。示例：智能体查看函数接口，发现需要传入会话 ID，然后使用 data 工具选取示例再执行。
- 环境变量：envList、envGet、envSet 和 envRemove 工具让智能体操作部署的环境变量。
使用方式
在 Cursor 上安装：进入“Cursor Settings > Tools & Integrations”，点击“Add a Custom MCP Server”，然后在 mcp.json 中填写“convex”部分。也可以按照 Cursor 文档，通过创建或编辑 ~/.cursor/mcp.json 文件添加全局 MCP 服务器。添加服务器后，确保“convex”服务器已启用并显示绿色（可能需要点击“Disabled”来启用）。
对于 MCP 服务器 beta 版，目前仅在 macOS Sequoia 上使用 Cursor 进行了测试。未来将在更多操作系统上测试更多智能体（如 Windsurf 和 Claude Desktop）。同时，使用相同的 npx -y convex@latest mcp start 命令配置这些工具应该可以工作。
适用场景
适用于使用 Convex 作为后端的开发者，希望让 AI 智能体辅助查询数据、运行函数、管理环境变量或编写一次性查询的场景。例如，在聊天应用中让智能体分析数据、查找高频词，或演示运行内部查询。
限制
- MCP 服务器处于 beta 阶段，仅测试了 Cursor on macOS Sequoia。
- MCP 客户端和服务器仍处于早期阶段，设计决策和变通方法可能随时间变化。
- 为兼容性选择了全局 MCP 服务器，因此同一计算机上所有 Convex 项目与同一 MCP 服务器通信，工具调用需传递项目目录。为避免混淆，工具协议要求模型仅在初始 status 调用时传递项目目录一次，返回一个不透明的“部署选择器”，后续调用只需传递该选择器。
- MCP 支持多种接口（Resources、Prompts、Tools、Sampling、Roots、Notifications），但 Cursor 和 Windsurf 目前仅支持工具，因此 Convex MCP 服务器仅通过工具暴露所有功能。
- 使用本地运行的 stdio 传输协议，所有 MCP 工具仅使用字符串参数，因为 MCP Inspector Tool 仅支持字符串参数，且嵌套 JSON 对象在 Cursor Agent 中无法通过 JSON schema 验证。
- 未来将添加更多工具、测试更多平台、整理更多工作流。
