Convex MCP Auth Bridge Failure

Support Bug Reports
1

Where does the bug appear (feature/product)?

Cursor IDE

Describe the Bug

CONVEX_DEPLOY_KEY Ignored in Agent Tool-Runner

While the Cursor UI successfully connects to a custom Convex MCP server (statusType: connected in logs), the Agent/Composer tool-runner fails to propagate the env block (containing CONVEX_DEPLOY_KEY) to the spawned subprocess.

Terminal: CONVEX_DEPLOY_KEY=prod:… pnpm convex:run succeeds (Auth is valid).
MCP Log: Shows successful stdio connection.
Agent Bridge: call_mcp_tool returns Not Authorized: Run npx convex dev to login.

MCP Config: Custom user-convex defined in ~/.cursor/mcp.json.
Tried env block injection and sh -c “export … ; npx …” injection. Both fail to provide the key to the CLI’s internal auth check when invoked by the AI agent.

Forced to decommission cloud-dev instances and rely on fragile terminal wrappers because the “Direct Wire” MCP integration is architecturally blind to the provided deployment keys.

Steps to Reproduce

Configure MCP Server: Add a custom MCP server (e.g., convex) in ~/.cursor/mcp.json with an env block containing a required credential (e.g., CONVEX_DEPLOY_KEY).

Verify UI Status: In Cursor Settings > Features > MCP, confirm the server is active and “Green”.

Attempt Agent Tool Call: In a Composer or Chat session, ask the agent to run a tool from that MCP server (e.g., status or tables).

Observe Failure: The agent will report a “Not Authorized” error or demand a manual login (e.g., npx convex dev), even though the env block in the config provides the necessary key.

Verify via Terminal: Manually execute the exact same command string in the Cursor terminal with the same environment variable (e.g., CONVEX_DEPLOY_KEY=… npx convex mcp start). Observe that it succeeds, proving the credential and command are valid.

Expected Behavior

The Agent/Composer tool-runner should propagate all environment variables defined in the env block of mcp.json to the spawned MCP subprocess. The agent should be able to execute authorized tool calls without prompting for manual, interactive login flows that it cannot complete.

Screenshots / Screen Recordings

Screenshot 2026-05-10 at 4.50.18 AM.png
Screenshot 2026-05-10 at 4.50.18 AM.png1590×1204 57.6 KB

Operating System

MacOS

Version Information

Version: 3.3.30 (Universal)
VSCode Version: 1.105.1

For AI issues: which model did you use?

Gemini Flash

Additional Information

There appears to be a regression in environment variable inheritance where the agent’s tool-execution bridge ignores the env section of the MCP configuration.
This creates an “authentication blind spot” for any non-interactive service that relies on local environment secrets.

Does this stop you from using Cursor

No - Cursor works, but with this issue

5

Resolved by Sonnet 4.6 inside of Cursor — root cause was Convex CLI v1.31.5, not Cursor

After deep investigation this turns out to be a Convex CLI bug, not a Cursor env propagation issue. The env block in mcp.json is being passed correctly to the subprocess. The failure happens inside the Convex MCP server itself.

Root cause: CONVEX_DEPLOY_KEY (prod:<name>|<key>) is a deployment-level credential. The Convex MCP server in v1.31.5 runs checkAuthorization() before every tool call, which calls https://api.convex.dev/api/authorize — a Big Brain (dashboard) endpoint that only accepts account-level OAuth tokens. In getBigBrainAuth(), the deploymentKey branch has higher priority than reading ~/.convex/config.json, so the deploy key is sent to an endpoint that rejects it with 401, regardless of whether valid OAuth credentials exist on disk.

Verification:

# Deploy key → 401

curl -I “https://api.convex.dev/api/authorize” -H “Authorization: Bearer prod:name|key”

# OAuth token → 200

curl -I “https://api.convex.dev/api/authorize” -H “Authorization: Bearer <accessToken from ~/.convex/config.json>”

Fix: Set CONVEX_OVERRIDE_ACCESS_TOKEN to the OAuth access token from ~/.convex/config.json. This variable is checked first in getBigBrainAuth() and wins over deploymentKey, allowing checkAuthorization() to pass while CONVEX_DEPLOY_KEY remains available for the actual deployment API calls.

A wrapper script (convex-mcp-start.sh) in mcp.json reads both credentials and sets both env vars on the spawned process. All MCP tools (status, tables, run, data, etc.) are now fully operational against the production deployment.

This is likely fixed in newer versions of the Convex CLI — the canonical npx -y convex@latest mcp start approach may not exhibit this behavior.