Convex MCP Server

What it does

The Convex MCP server is part of the Convex command-line tool and starts with `convex mcp start`. Its code lives in the npm-packages/convex folder of the open-source Convex backend repository, which also holds the database engine itself. It talks to a Convex deployment, cloud or self-hosted, and gives an assistant twelve tools for working with it while building an app.

The `status` tool comes first: it finds the deployments for a project folder and returns a selector the other tools take. With that, an assistant can list tables with their declared and inferred schemas, page through a table's documents, run a read-only JavaScript query in a sandbox, read the specs of deployed functions and call them, pull recent function logs, look at 72 hours of health insights (write conflicts, read limits), and list, read, set or remove deployment environment variables.

By default it works on the project's development deployment. Flags pick another one (`--prod`, `--preview-name`, `--deployment-name`, `--env-file`), change the project folder (`--project-dir`), or switch off tools (`--disable-tools`). In the source, `data` returns 100 documents per page by default, up to 1000 with `limit`, and `logs` trims its answer to about 20000 tokens by default (`tokensLimit`) (npm-packages/convex/src/cli/lib/mcp/tools/data.ts and logs.ts).

What it needs

Node.js with npx, a Convex project and either a signed-in Convex CLI (`npx convex login`) or a deploy key in CONVEX_DEPLOY_KEY. For a self-hosted backend, an env file holding CONVEX_SELF_HOSTED_URL passed with `--env-file`. The client should start it from the project folder or be given `--project-dir`.

Limits

Production deployments are limited by default: only insights, tables and functionSpec work there; data, logs and runOneoffQuery need `--cautiously-allow-production-pii`, and env reads plus run, envSet and envRemove need `--dangerously-enable-production-deployments`. `--project-dir` does not stop an assistant from naming another project folder or deployment. The insights tool does not work when started with CONVEX_DEPLOY_KEY. runOneoffQuery cannot change data. There are no tools to deploy code, edit the schema or write documents directly; writes go through deployed functions via run.

Who it suits

Suits developers building on Convex who want an assistant to see their real schema, data, function signatures and logs while it writes code, mostly against a dev deployment. Teams that need a hard boundary should start it with a scoped deploy key and `--disable-tools`, since with a plain CLI login it can reach every project the account can. It is of no use without a Convex deployment. To expose your own app's data to your users' assistants, Convex's separate MCP component (get-convex/mcp) is the tool for that, not this server.