Convex MCP Server Cursor IDE Setup 2026

Unlike most integrations in this series, there's no separate package to install for Convex. The MCP server ships inside the Convex CLI itself — if you're already running a Convex project, you already have it. One command, npx -y convex@latest mcp start, starts the server against your existing deployment.

That also means this guide doesn't apply if you don't have a Convex project yet. This isn't a general-purpose "connect to any backend" tool — it's introspection and control for a specific Convex deployment you're already developing against.

What the Convex MCP Server Exposes

The tool set is deployment introspection and control, not a generic database client:

That run tool is the one to be deliberate about — it executes real functions against a real deployment, mutations included if your account has access.

Why This Beats Switching to the Dashboard

Convex's dashboard is already good for browsing data, but the MCP connection collapses the loop of "write a mutation, switch to the dashboard, run it manually, switch back" into one chat turn. Ask Cursor to run a query, look at the result, and immediately iterate on the function's code in the same session — no context switch, and the AI has the actual return shape in front of it while it writes the next line of code.

The logs and insights tools matter more than they sound like on paper: when a function is misbehaving, pulling real execution logs into the same chat where you're editing the function's code means Cursor is debugging against actual runtime behavior, not a hypothetical.

Prerequisites

Step 1: Confirm You're Logged In

npx convex login

This opens a browser to authenticate your CLI session with your Convex account. Skip this if you're already logged in from setting up the project.

Step 2: Add the Server via Cursor's Settings UI

Open Cursor Settings → Tools & Integrations → New MCP Server. This opens mcp.json directly — add a convex entry:

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

No API key or token goes in this config — authentication is handled by your existing CLI login from Step 1, and the server operates against whichever Convex project directory Cursor is running in.

Step 3: Restart and Verify

Restart Cursor and check the MCP panel for a connected "convex" entry. Then, from inside your Convex project, try:

List the tables in my Convex deployment and show me their schemas

If you get back real table names and field definitions, you're connected.

Production Access Is Off by Default

By design, the server restricts access to your development deployment unless you explicitly opt in. To allow it to touch a production deployment, add the flag:

"args": ["-y", "convex@latest", "mcp", "start", "--dangerously-enable-production-deployments"]

The naming is deliberate — think carefully before enabling this on a shared config, since it means every tool call the AI makes (including run, which can trigger mutations) can now execute against production data. For most day-to-day development, leave this off and let the server operate against your dev deployment only.

Practical Workflows

Debugging a failing function without leaving the editor

My createOrder mutation is failing intermittently. Pull the last 20 log 
entries for it and show me what's actually happening before I start 
guessing at the fix.

Iterating on a query's return shape

Run the listActiveUsers query and show me exactly what it returns. 
I want to update the frontend component to match the real shape, 
not what I assumed it would be.

Checking deployment health

Give me the health insights for this deployment over the last 72 hours — 
anything that looks like an emerging problem?

Environment variable audit

List the environment variables set on this deployment. I need to confirm 
STRIPE_WEBHOOK_SECRET is actually set before I debug why webhooks aren't validating.

Gotchas

run executes real functions, mutations included. Unlike the read-only runOneoffQuery and data tools, asking Cursor to "run" a named function calls it for real. If that function writes to your database, that write happens. Be as deliberate about this as you would be pasting a mutation call into your own terminal.

The server only sees the project directory it's running in. If you have multiple Convex projects, the connection is scoped to whichever one your Cursor session's working directory points at — it doesn't automatically discover other projects on your machine.

Production is gated for a reason, not an inconvenience. The --dangerously-enable-production-deployments flag exists because the default behavior — dev-only — is the safe one. Don't add that flag to a shared or committed mcp.json just to save a step; scope it to sessions where you specifically intend to touch production.

Troubleshooting

"No deployment found" or similar errors
Confirm you're running Cursor with the project's directory as the working root, and that convex.json actually exists there. The MCP server infers context from the project directory — it's not a standalone service you connect to from anywhere.

Server starts but every tool call fails with an auth error
Run npx convex login again — CLI sessions can expire, and the MCP server relies on that same login rather than a separate credential.

run fails on a function that works fine through npx convex run
Check whether the function requires arguments the AI didn't pass, or whether it's gated by an auth context the MCP session doesn't have (e.g., a function that expects an authenticated user identity). Some functions are written assuming they're only ever called from your app's authenticated client, not a bare CLI-style invocation.

Production writes happened that I didn't expect
If --dangerously-enable-production-deployments was left on in a config from a previous session, every run call against a mutation was live against production the whole time. Remove the flag immediately and audit recent writes via Convex's dashboard.

Frequently Asked Questions

Q: Do I need a separate npm package for Convex MCP, like most other integrations?
A: No — it's built into the Convex CLI itself. Running npx -y convex@latest mcp start is the whole install step; there's no standalone @convex/mcp-server package to add separately.

Q: Can the MCP server write to my database, or is it read-only?
A: It can write. The run tool executes real Convex functions, including mutations, against your deployment. data and runOneoffQuery are read-only, but run is not — treat prompts that invoke it with the same care as running that function manually.

Q: Does this work against my production deployment by default?
A: No — production access is disabled by default and requires the explicit --dangerously-enable-production-deployments flag. Without it, the server only operates against your development deployment.

Q: What happens if I have multiple Convex projects on my machine?
A: The MCP server is scoped to whichever project directory Cursor's session is running in (identified by the local convex.json). It doesn't span multiple projects in one connection — run separate sessions per project if you need to work across more than one.

Q: Can I use this to audit or change environment variables without opening the dashboard?
A: Yes — envList, envGet, envSet, and envRemove are all exposed as tools, so you can read and modify a deployment's environment variables directly from Cursor chat.

Q: Is there a way to see recent errors without pulling full logs?
A: The insights tool is built for exactly this — it returns health insights over roughly the last 72 hours rather than a raw log dump, which is usually faster for spotting an emerging problem than reading through logs output line by line.

Related Guides

---