Convex

Convex is a reactive backend platform that provides developers with capabilities such as a database, functions, workflows, synchronization, search, and file storage, all based on TypeScript, with no need to write glue code. Convex version 1.19.5 introduces a beta MCP server, used to let AI agents introspect deployment status, run functions, and read and write data.

Purpose

The Convex MCP server is mainly aimed at AI agents, enabling them to interact with Convex deployments. MCP (Model Context Protocol) is a standardized protocol used for interaction between AI agents and different tools, such as reading the local file system, searching the web, or controlling a browser. Convex's MCP server supports introspecting a deployment's tables and functions, calling functions, reading and writing data, and allows agents to write one-off query code. Because Convex queries are fully sandboxed and cannot write to the database, it is safe to let agents operate freely.

Main capabilities

• Status query: The status tool lets the model query the deployments it can access and returns a "deployment selector" that can be passed to subsequent tool calls. Each application deployed to Convex corresponds to a project, and a project can have multiple deployments: one production deployment, one development deployment per team member, and possibly multiple preview deployments.
• Table listing: The tables tool lists all tables in a deployment, returning table names, declared schemas (if any), and inferred schemas. Convex automatically tracks data shapes, so even if no schema is declared, agents can use this to suggest schema improvements, such as filling in v.any() types or discovering unused optional fields.
• Data pagination: The data tool is used to paginate through documents in a table.
• One-off queries: The runOneoffQuery tool allows the model to write code to query deployment data. The code is fully sandboxed and cannot modify the database, so it is harmless. Example: write a one-off query to find the most frequently occurring words in the messages of a chat application.
• Function specifications: The functionSpec tool lets the model view all deployed functions and their types and visibility. Compared with reading all the code under the convex/ directory, obtaining the API in a single tool call is more efficient.
• Run functions: The run tool is used to actually run functions. Example: the agent views the function interface, finds that a session ID needs to be passed in, and then uses the data tool to select an example before executing.
• Environment variables: The envList, envGet, envSet, and envRemove tools let agents operate on a deployment's environment variables.

How to use

Install on Cursor: go to "Cursor Settings > Tools & Integrations", click "Add a Custom MCP Server", and then fill in the "convex" section in mcp.json. You can also add a global MCP server by creating or editing the ~/.cursor/mcp.json file, following the Cursor documentation. After adding the server, make sure the "convex" server is enabled and shows green (you may need to click "Disabled" to enable it).

For the beta version of the MCP server, it has currently only been tested using Cursor on macOS Sequoia. In the future, more agents (such as Windsurf and Claude Desktop) will be tested on more operating systems. At the same time, using the same npx -y convex@latest mcp start Configuring the command for these tools should work.

Applicable scenarios

Suitable for developers using Convex as a backend who want AI agents to assist with querying data, running functions, managing environment variables, or writing one-off queries. For example, in a chat application, letting the agent analyze data, find high-frequency words, or demonstrate running internal queries.

Limitations

• The MCP server is in beta, and only Cursor on macOS Sequoia has been tested.
• MCP clients and servers are still in an early stage, and design decisions and workarounds may change over time.
• For compatibility, a global MCP server was chosen, so all Convex projects on the same computer communicate with the same MCP server, and tool calls need to pass the project directory. To avoid confusion, the tool protocol requires the model to pass the project directory only once in the initial status call, returning an opaque "deployment selector"; subsequent calls only need to pass that selector.
• MCP supports multiple interfaces (Resources, Prompts, Tools, Sampling, Roots, Notifications), but Cursor and Windsurf currently only support tools, so the Convex MCP server exposes all functionality only through tools.
• It uses the locally running stdio transport protocol, and all MCP tools use only string parameters, because the MCP Inspector Tool only supports string parameters, and nested JSON objects cannot pass JSON schema validation in Cursor Agent.
• More tools will be added in the future, more platforms will be tested, and more workflows will be organized.