Cursor MCP Not Working: 8 Fixes for Connection Errors

Cursor MCP not working usually means one of three things: your mcp.json points to a path that doesn't exist, the server binary crashed on launch, or Cursor is reading an old Claude Desktop config instead. The first fix—checking the absolute path in your MCP settings and running 'MCP: Refresh Servers'—solves most cases in under two minutes.

Most developers assume MCP is plug-and-play, copy a snippet from docs, and hit a silent failure when Cursor's agent mode shows zero tools. Here's every failure mode I've diagnosed in production Cursor setups, the exact terminal commands to verify each piece, and the one-click alternative when you need the AI to see exactly what's wrong on screen without writing selectors by hand.

Why does Cursor say "No MCP servers available" even after I added mcp.json?

Cursor reads ~/.cursor/mcp.json on launch and when you manually refresh. If the file exists but the command field points to a nonexistent binary or a relative path, the server appears in settings but never connects.

Open Terminal and verify the path exists:

ls -lh ~/.pinvari/mcp/pinvari-mcp

If that returns "No such file or directory," the server isn't installed. For PinVari's MCP connector, you install it once inside the app (PinVari → Connect → Cursor), which copies the binary to ~/.pinvari/mcp/. Other MCP servers (filesystem, git, web-search) require an npm install -g or pip install step before you add them to mcp.json.

Next, check that your JSON is valid:

cat ~/.cursor/mcp.json | jq .

If jq throws a parse error, you have a trailing comma, unescaped backslash, or missing quote. Fix it, then run the command palette (⌘⇧P) → MCP: Refresh Servers. Cursor won't auto-reload the file on save.

How do I know if the MCP server is actually running?

A connected MCP server shows a green dot in Cursor's bottom bar (near the branch name). Click it to see the list of registered tools and resources. If your server appears grayed out or says "Starting…" forever, the binary crashed during initialization.

Check the MCP logs:

tail -f ~/.cursor/logs/mcp-*.log

Common crash causes: missing environment variables (ANTHROPIC_API_KEY for servers that call Claude directly), wrong Node.js version (some servers need v18+, check with node -v), or a Python server launched without activating its virtualenv.

For PinVari's MCP connector, the app itself must be running—the connector talks to it on 127.0.0.1:3402. If you quit PinVari, the tools disappear from Cursor's agent mode. Launch PinVari, wait for the menu-bar icon, then refresh MCP in Cursor.

What does "MCP tool execution failed" mean in agent mode?

This error appears after the server connected successfully but the tool call itself threw an exception. The agent tried to invoke a function—say, pinvari_next_instruction or read_file—and the server returned a 500 or timed out.

Open the MCP server's own log (not Cursor's log). For PinVari:

tail -f ~/.pinvari/logs/mcp-connector.log

Look for stack traces. Typical causes:

• Permission denied: the server tried to read a file outside its allowed scope, or macOS sandboxing blocked it. Grant Full Disk Access in System Settings → Privacy & Security → Full Disk Access → add Cursor.app.
• Timeout: the operation took >30s. For screenshot-based tools like pinvari_next_instruction, this happens if you forgot to actually draw a mark on screen—the server waits indefinitely for a capture that never comes. Press ⌥⌘A, circle the UI element, press ⏎ to finish.
• Malformed parameters: the agent hallucinated a JSON argument schema. Check cursor rules to constrain how the agent formats tool calls.

After fixing the root cause, rerun the agent task. It resumes from the last successful step.

Why does Cursor agent mode ignore my MCP tools and use built-in web search instead?

Cursor agent mode prioritizes tools that match the user's phrasing. If you say "search for XYZ," it calls a web-search tool. If you say "fix this button," it edits code directly and never checks MCP unless the task explicitly needs filesystem or screenshot context.

Force the agent to check MCP tools by naming the capability in your instruction:

"Use the pinvari_next_instruction tool to see what I circled, then update the CSS."

Or add a cursor rule in .cursorrules:

When the user describes a UI issue ("this dropdown", "that form"), always call pinvari_next_instruction to resolve the exact element before editing code.

Cursor loads .cursorrules from your project root on every agent invocation. This is more reliable than hoping the agent discovers MCP tools by accident.

How do I debug "context used: 145K tokens" but the agent still doesn't see my screen?

Cursor context used counts tokens from open tabs, recent edits, docs, and—if you enabled it—the agent's memory. It does not include screenshot pixels unless you explicitly attach an image or an MCP tool provides one.

Check what's in context:

1. Open the chat panel (⌘L).
2. Scroll to the top of the agent's reply. Cursor shows "Context: 23 files, 145K tokens" as a dropdown. Click it.

You'll see file paths and line ranges. If the on-screen UI isn't in that list, the agent guessed which component to edit based on your description, not the actual visual state.

To get the agent's attention on a specific on-screen element:

• Screenshot + describe: attach a screenshot, then type "the red button in the top-right." The agent sees pixels but still guesses coordinates.
• Use an MCP screenshot tool: best screenshot MCP servers return both the image and structured metadata (window title, OCR text, sometimes coordinates). The agent gets a named anchor.
• Point and speak with PinVari: press ⌥⌘A, circle the element, say "make this bigger." PinVari resolves the exact accessibility element (role, label, frame), transcribes your speech on-device, and hands the agent a precise instruction: "AXButton 'Submit' at {x: 520, y: 340}, user said: make this bigger." Zero ambiguity. Install from pinvari.com, connect via PinVari → Connect → Cursor (one click), then the agent's pinvari_next_instruction tool returns the cropped region + named element path.

What if mcp.json is valid but Cursor still shows "Failed to start MCP server"?

This is a binary-launch failure. The server process exits before Cursor can establish the stdio connection. Run the command manually to see the real error:

~/.pinvari/mcp/pinvari-mcp

(Substitute your server's path.) Common exit reasons:

After fixing, restart Cursor (⌘Q, relaunch). The MCP: Refresh Servers command won't pick up a binary that failed to execute on launch.

Can I use the same MCP server in both Cursor and Claude Code?

Yes, but you configure each separately. Cursor MCP uses ~/.cursor/mcp.json. Claude Code MCP uses ~/.config/claude/mcp.json (Linux/macOS) or a user-scoped claude mcp add command. Both can point to the same binary—for example, ~/.pinvari/mcp/pinvari-mcp—but the connector must support concurrent clients or run as separate instances.

For PinVari, the MCP connector is single-client (one agent at a time talks to the app on 127.0.0.1:3402). If you want to use it in both editors, run it in one at a time, or open two captures in the PinVari Command Center and route them manually. Most filesystem/git/web MCP servers are stateless and handle multiple clients fine.

The config shape differs slightly:

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "pinvari": {
      "command": "/Users/you/.pinvari/mcp/pinvari-mcp",
      "alwaysAllow": ["read_resource", "write_resource"]
    }
  }
}

Claude Code (CLI):

claude mcp add --scope user pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp"

Same connector, different registration. Never write claude mcp add pinvari without the full path—it errors.

How do I test if Cursor agent mode can actually call my MCP tool?

Open Cursor's chat (⌘L), type:

"List all available MCP tools."

The agent replies with a table of registered tools and their descriptions. If your server appears, try a direct invocation:

"Call pinvari_next_instruction and show me the result."

If it works, you see the tool's return value in the chat. If it fails with "tool not found," the server didn't register the tool properly—check the server's own logs for initialization errors.

For PinVari specifically, the tool pinvari_next_instruction only succeeds after you drew a mark on screen. If you call it without pressing ⌥⌘A and circling something, it returns {"status": "no pending captures"}. That's expected. Press the hotkey, mark an element, then rerun the agent instruction.

FAQ

Why does Cursor say "MCP server crashed" after working fine yesterday?

The server binary or its dependencies changed. Check if you upgraded Node/Python, changed environment variables, or if macOS revoked permissions (System Settings → Privacy & Security → Full Disk Access). Restart Cursor and inspect ~/.cursor/logs/mcp-*.log for the exit reason. Most crashes are missing API keys or file-permission denials.

Can I use Cursor MCP offline?

Only if the MCP server itself is fully local. Servers that call external APIs (web-search, cloud-based OCR, remote git) fail without internet. PinVari's MCP connector is fully on-device—screenshot, transcription, AX tree resolution—so it works offline. The Cursor agent still needs network to reach Anthropic's API unless you configured a local LLM endpoint.

What's the difference between Cursor rules and MCP tools?

Cursor rules are plaintext instructions in .cursorrules that bias how the agent writes code (style, patterns, constraints). MCP tools are executable functions the agent calls to read files, take screenshots, or query databases. Use rules to enforce "always use Tailwind," use MCP tools to give the agent real-time screen context. Combine both: a rule that says "always call pinvari_next_instruction before editing UI" + the MCP tool that resolves the element.

How many MCP servers can I register in Cursor at once?

No hard limit in the JSON schema, but each server adds latency to Cursor's startup and token overhead to the agent's system prompt (every tool gets a description). I've run 12 servers simultaneously without issues. Beyond ~20, the agent's context fills with tool schemas and you hit the model's limit before adding any code. Prune unused servers. Keep 3–8 high-signal tools.

Why does the agent keep asking "which file should I edit" even after I used an MCP screenshot tool?

The screenshot tool returned an image and maybe OCR text, but no file path or component identifier. The agent sees "button labeled Submit" but doesn't know if that's Button.tsx or dashboard/actions.ts. Point-and-speak tools (PinVari) return the accessibility element path (app name, window title, AXButton role/label, frame), which the agent cross-references with open files. If you don't have that, paste the file path in the follow-up or use a cursor rule: "UI fixes always edit src/components/".

Can I connect Cursor MCP to a remote server over SSH?

Not directly—Cursor's mcp.json expects a local command binary. You can wrap an SSH command in a shell script that forwards stdio, but latency kills the experience (every tool call = SSH round-trip). Better: install the MCP server on your local machine and point it at the remote repo via git or a mounted filesystem. For screenshot/UI tools like PinVari, remote makes no sense—the macOS Accessibility API is local-only.