Convex MCP Server

Introspect deployment state, run functions, manage env vars, and read/write data in Convex backends from an AI agent.

Developer Tools by Convex None active

Overview

The Convex MCP server is built directly into the Convex CLI (version 1.19.5+) and lets AI agents interact with Convex deployments over the Model Context Protocol. It is launched locally via npx convex mcp start and communicates with the agent over stdio. After initial authentication with Convex, the server exposes a set of tools for inspecting tables, reading documents, running queries and mutations, viewing logs, checking deployment health, and managing environment variables.

The server is designed for use inside the project directory of a Convex app and uses opaque "deployment selectors" returned by the status tool so the agent does not have to pass project paths around on every call. By default, production deployments are blocked. Read access to production requires an explicit flag, and write access requires --dangerously-enable-production-deployments. Individual tools can be disabled with --disable-tools for finer control over what an agent can do.

Because the MCP server ships as part of the standard convex npm package maintained by the Convex team (source under get-convex/convex-backend), it stays in lockstep with the rest of the platform and supports the same dev, preview, and prod deployment model used by the CLI.

Tools

Tool	Description
`status`	Queries available deployments and returns an opaque deployment selector used by other tools.
`tables`	Lists all tables in a deployment with declared and inferred schemas plus metadata.
`data`	Paginate through documents in a specified table.
`runOneoffQuery`	Write and execute a sandboxed read-only JavaScript query against deployment data.
`functionSpec`	Returns metadata about deployed functions including types, visibility, and argument shapes.
`run`	Executes a deployed Convex function (query, mutation, or action) with supplied arguments.
`logs`	Fetches a chunk of recent function execution log entries as structured objects.
`insights`	Fetches health insights for the last 72 hours, including OCC conflicts and resource limit issues.
`envList`	Lists all environment variables for a deployment.
`envGet`	Retrieves the value of a specific environment variable.
`envSet`	Creates or updates an environment variable on the deployment.
`envRemove`	Deletes an environment variable from the deployment.

Setup Guide

Prerequisites

Node.js installed
A Convex project (run inside a directory with a convex/ folder and .env.local)
Convex CLI version 1.19.5 or later (npx convex@latest)
You must have already logged in / linked a deployment with npx convex dev at least once

Start command

npx -y convex@latest mcp start

Claude Desktop / Cursor / Windsurf config

Add to your MCP client config (e.g. ~/.cursor/mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "convex": {
      "command": "npx",
      "args": ["-y", "convex@latest", "mcp", "start"]
    }
  }
}

Claude Code

claude mcp add-json convex '{"type":"stdio","command":"npx","args":["convex","mcp","start"]}'
claude mcp get convex

Useful flags

--project-dir /path/to/project lock the server to a single Convex project
--prod allow access to production deployments (read-only by default)
--dangerously-enable-production-deployments allow write/mutating tools against production
--preview-name <name> target a preview deployment
--deployment-name <name> target a specific deployment
--env-file <path> use a custom env file
--disable-tools data,run,envSet disable specific tools by name

Use Cases

Let an AI coding agent explore an unfamiliar Convex schema by listing tables and paginating sample documents before writing new functions
Debug failing requests by pulling recent function logs and correlating them with the insights tool to spot OCC conflicts or rate limits
Run ad hoc read-only JavaScript queries via runOneoffQuery to answer data questions without writing a new query function
Invoke deployed mutations and actions via run to seed dev data, trigger workflows, or reproduce bugs
Manage deployment configuration by listing, reading, setting, and removing environment variables directly from the agent

Example Prompts

"List the tables in my Convex dev deployment and show the inferred schema for the messages table."
"Run a oneoff query to count documents in users created in the last 24 hours."
"Tail the most recent function logs and tell me what's throwing errors."
"Check insights for my deployment and report any OCC conflicts from the last 72 hours."
"Set the STRIPE_WEBHOOK_SECRET env var on my dev deployment to the value I just pasted."

Pros

Maintained by the Convex team and shipped as part of the official convex npm package, so it tracks platform changes
Broad tool coverage: schema, data, function execution, logs, health insights, and env vars all in one server
Sensible production safety defaults (prod is blocked unless explicit flags are passed)
Per-tool disable flag (--disable-tools) lets you restrict what an agent can do

Limitations

Requires a local Convex project directory and prior convex dev setup; cannot be used as a hosted remote server
Production writes require an explicit "dangerously" flag, which is intentional but means routine prod operations need extra care
runOneoffQuery is read-only by design, so write/mutation experiments must go through deployed functions via run

Alternatives

Supabase MCP server for hosted Postgres backends with similar schema/data/SQL access
Neon MCP server for Postgres deployment management via MCP
PlanetScale or generic Postgres MCP servers for SQL-first backends