Cursor MCP Integration: Wire Local Tools in Minutes

Cursor MCP integration is the act of registering a Model Context Protocol server so Cursor's Agent can call that server's tools from a chat. You do it by writing a server block in ~/.cursor/mcp.json (or a project .cursor/mcp.json), restarting Cursor, and confirming the tools show green under Settings, MCP.

Most writeups stop at "paste this JSON". The part that actually changes your day is what the server returns: a named element with a confidence score, or just another screenshot the model has to guess from.

What does a cursor mcp integration actually do?

MCP is a wire protocol. Cursor is the client. Each server exposes named tools the Agent can invoke, the same way it would call a function.

A cursor mcp integration is not a plugin marketplace install. It is a config entry that tells Cursor how to launch or connect to a process, plus a handshake that lists the tools.

The interesting case on a Mac is a local server on 127.0.0.1. Nothing leaves the machine unless your model call sends it.

That is the difference between a SaaS sidecar and a tool that can read the window you are looking at.

How do I set up a cursor mcp integration in Cursor?

Three durable steps. One-click installers exist; they write the same files.

1. Open the right config

Cursor reads two files. Global: ~/.cursor/mcp.json. Project: .cursor/mcp.json in the repo root.

Project wins on name collision. Put always-on tools in the global file. Put repo-only tools in the project file.

2. Add a server block

A stdio server (Cursor launches a local binary) looks like this:

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

An HTTP or SSE server you already started looks like this:

{
  "mcpServers": {
    "local-tools": {
      "url": "http://127.0.0.1:3402/sse"
    }
  }
}

Keep secrets out of the file. Use environment references, not pasted keys. mcp.json leaks into dotfile repos.

3. Restart and verify

Fully quit Cursor. Reopen. Open Settings, MCP. A healthy server shows a green dot and a tool list.

Enable the server for Agent mode. Then ask the Agent to call a tool by name so you see a real round trip, not just a green light.

What is the one-click path versus hand-edited JSON?

If the tool ships a connector, use it. PinVari writes its binary under ~/.pinvari/mcp/pinvari-mcp and can register from PinVari → Connect → Cursor.

The CLI form for Claude-family clients is the same binary:

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

Never run the bare claude mcp add pinvari. It errors. The app must be installed and running, because the connector talks to it on 127.0.0.1:3402.

Hand-editing JSON is still the escape hatch. One-click is just a writer for that file.

Which servers are worth integrating first?

Start with tools that return structure, not more tokens.

Filesystem or repo tools

Type: stdio Gives the Agent: file contents it already had via the editor When it helps: remote or unusual worktrees Limit: does not tell the Agent which button you meant

Browser or docs tools

Type: HTTP or stdio Gives the Agent: page text, search hits When it helps: reading a spec while coding Limit: cannot see a native Mac window

Screen-context tools

Type: local stdio talking to a Mac app Gives the Agent: role, label, frame, spoken instruction, cropped region When it helps: "this dropdown is wrong" in a running app Limit: AX can be empty on canvas and some games; then you need OCR

The third category is the one most Cursor MCP integration guides skip. MCP tools lists the shapes; what is an MCP server is the plain-language version.

A capture that also binds deictic words ("this", "that") to the pointer at the instant you said them is more useful than a full-window PNG. PinVari does that on-device and hands the bundle to Cursor over the local server.

What should the Agent receive on a good integration?

A useful tool result for UI work has five parts.

Resolved element. Role, label or title, frame, parent chain. From the macOS Accessibility API when the tree is honest.

Confidence and provenance. Circled versus dwelled. Below about 0.8, the honest rule is ask, never silently guess.

Spoken instruction, per mark. Circle three things in one breath and each mark keeps its own words.

Cropped screenshot. Evidence, not the only signal. Full-window dumps waste context. See how screenshots waste Claude Code tokens for the same problem in another client.

Window extras. Focused-window text (PinVari reads up to 40,000 characters, including text scrolled out of view), the browser URL from AXWebArea, optional on-device OCR on AX-blind surfaces.

That bundle is what turns "fix the button" into an executable instruction.

How do I test the integration without fooling myself?

Do not stop at a green dot.

Ask Agent mode: "List the tools on the pinvari server and call the health check." You want a tool-call block in the transcript, not a hallucinated "I can see your tools."

Then run a real capture. Hold ⌥⌘A, circle a labeled button, say "make this primary." Confirm the tool return includes the button's AX name, not just pixels.

If the name is empty, you hit a lazy Electron or Chromium tree. PinVari sets AXManualAccessibility and retries for about 150ms; other servers may not. That is a product difference, not a Cursor bug.

If confidence is low, the Agent should ask which control you meant. If it edits the neighbor anyway, the integration is lying about provenance.

What breaks a cursor mcp integration?

These are the cases I see, in order.

Wrong path. command is not on PATH and is not absolute. Cursor starts nothing. The panel shows zero tools.

Server not running. HTTP/SSE entries need a listener. Stdio entries need a binary that stays up long enough to handshake.

App not running. A connector that talks to 127.0.0.1:3402 fails if the Mac app is quit. Start the app, then retry.

Project config shadowing global. You added the server globally, then opened a repo with an empty or conflicting .cursor/mcp.json.

Permissions. Screen or Accessibility permission denied. The server process starts, tools list, then every capture is empty.

Transport mismatch. You pointed a stdio client at a URL, or an HTTP client at a binary.

Fix those before you blame the model. Cursor MCP integration bugs are almost always config, process, or permission.

How does this change a Claude Code or Cursor UI loop?

I used to paste a screenshot and a paragraph. The Agent edited the wrong row. Tokens went to pixels.

Now the loop is: mark the control, speak the change, let the Agent pull pinvari_next_instruction, then pinvari_mark_done when it is finished. Mid-task it can call pinvari_request_capture and the notch island asks me to point again.

That is the same MCP surface Cursor and Claude Code share. Integration once, use in whichever client is open.

The Mac app is a one-time launch license. The model is yours. Nothing is uploaded by default.

How do I keep a cursor mcp integration alive across Cursor updates?

Pin the command to an absolute path. PATH changes after updates are the usual breakage.

Export a copy of mcp.json in your dotfiles without secrets. When Cursor resets the file, you can restore the block in a minute.

After a Cursor update, open Settings, MCP before you trust Agent mode. A green dot yesterday is not a contract.

If you use a project file, tell teammates in the README. A cursor mcp integration that only lives on your laptop is a demo.

Absolute path plus a green-dot check after every client update.

FAQ

Does Cursor MCP integration require a paid Cursor plan?

Agent mode and MCP are product features on Cursor's current plans; check your account if a panel is missing. The local server itself is independent of Cursor billing. You can run the same connector from Claude Code or Codex.

Where should I put mcp.json for a team?

Keep machine-local servers in each person's ~/.cursor/mcp.json. Commit a project .cursor/mcp.json only for repo-specific servers and never with secrets. Document the one-click or CLI install in the README.

Why does Settings, MCP show 0 tools after a correct JSON edit?

Cursor did not re-read the file, the command path is wrong, or the process exited on startup. Quit Cursor, run the command in Terminal by hand, and watch stderr. A binary that prints and dies will always show zero tools.

Can I integrate more than one MCP server?

Yes. mcpServers is a map. Name each server and enable the ones you want per chat. Too many tools confuse the Agent; keep the set small and high-signal.

Is a local cursor mcp integration private?

The server on 127.0.0.1 does not upload by itself. The model provider still sees whatever the Agent puts in the prompt, including tool results you allow it to send. On-device transcription and OCR stay on the Mac until you hand a capture over.

Do I need to write an MCP server to use this?

No. You integrate servers other people ship. Writing one is only worth it if you have a tool no client can call today. Start by wiring a screen-context or repo server and learn the handshake first.