Should I use global or project-level MCP config in Cursor?

Global (~/.cursor/mcp.json) for tools you want everywhere. Project-level (.cursor/mcp.json) for tools specific to one repo. ToolPiper is usually global because it runs on your Mac regardless of which project you're in. Project-level makes sense if your team uses different MCP servers per project.

How do I remove ToolPiper from Cursor?

Delete the toolpiper entry from mcp.json and restart Cursor. ToolPiper itself keeps running for other clients.

Can I use ToolPiper alongside Cursor's marketplace MCP servers?

Yes. Cursor combines all registered MCP servers (marketplace + custom JSON config) into a single tool catalog the agent sees. There's no conflict between the marketplace path and the manual JSON path.

Does Cursor's agent call ToolPiper tools automatically?

Yes. Cursor's agent treats ToolPiper tools like any other tool. The model picks tools based on the conversation. You can name a tool explicitly to force its use ("call vision_screenshot"), but you usually don't need to.

Why does Cursor say "MCP server failed to load" after I save the file?

Cursor doesn't hot-reload mcp.json. You have to restart Cursor for changes to take effect. Some versions also fail silently if the JSON is malformed. Validate the file (run it through python3 -m json.tool or similar) before assuming the registration is wrong.

Cursor MCP Setup: Add ToolPiper for 300+ Local Tools on Mac

Cursor's MCP support landed late 2024 and matured fast. It supports HTTP MCP servers natively, which means ToolPiper drops in without a stdio wrapper or a marketplace listing. The whole setup is a JSON file edit.

Why connect Cursor to ToolPiper?

Cursor's agent and chat modes work with MCP tools out of the box, but the cloud-hosted MCP servers in Cursor's marketplace can't reach your local Mac state. ToolPiper exposes over 300 tools that run on your machine: screen capture, system control, local LLM chat, browser automation, audio transcription. None of them require a cloud round-trip beyond the editor itself.

A few concrete examples once ToolPiper is connected. Ask Cursor "what's on my other monitor" and it reaches for vision_screenshot + vision_ocr. Tell it to "open the staging dashboard and check the latency chart" and you get browser_launch + browser_snapshot with AX tree extraction. Route a summarize prompt through chat against a local LLM and Cursor's cloud never sees the transcript. macOS itself becomes scriptable from the chat too: resize windows, switch Spaces, adjust focus modes, manage Calendar events.

How do I add ToolPiper to Cursor?

Edit ~/.cursor/mcp.json for global access, or .cursor/mcp.json inside a project directory for per-project access. Add a toolpiper entry with type: "http" and url: "http://127.0.0.1:9998/mcp". Restart Cursor.

The JSON:

{
  "mcpServers": {
    "toolpiper": {
      "type": "http",
      "url": "http://127.0.0.1:9998/mcp"
    }
  }
}

If the file doesn't exist, create it with that content. If it exists with other MCP servers already, add toolpiper to the mcpServers object alongside them.

Three steps:

Edit the file. ~/.cursor/mcp.json for global, .cursor/mcp.json for per-project.
Save. Cursor doesn't watch the file. Saving alone won't trigger a reload.
Restart Cursor. Quit fully and relaunch. A window close isn't enough on most builds.

Where does the file live?

Two locations. ~/.cursor/mcp.json is the user-level config, applies to every Cursor session on this Mac. .cursor/mcp.json inside a project directory is the project-level config and overrides the user-level one for that project.

Pick global if you want ToolPiper available everywhere. Pick project-level if you want different MCP servers per repo (which is reasonable for shared projects where teammates might not all have ToolPiper installed).

If you go project-level and the repo is shared, gitignore .cursor/mcp.json. The file references local paths and ports that aren't portable across machines.

How do I verify Cursor sees ToolPiper?

Open Cursor settings, find the MCP section, ToolPiper should appear with a green status indicator. Or open a chat and ask for something only ToolPiper can do. If the model invokes a tool like vision_screenshot, the connection works.

Cursor's settings page lists registered MCP servers with their connection status. A green dot or check mark means the handshake succeeded. A red dot means Cursor couldn't reach the server. The most common cause is ToolPiper not running.

An end-to-end test from a chat: "Take a screenshot of my screen and tell me what's on it." If Cursor invokes the tool and reports back, the wiring is correct. If it says something like "I don't have a tool for that", the registration didn't take.

What if Cursor can't see ToolPiper?

Four checks in order. ToolPiper is running. The JSON file is valid. You fully quit and relaunched Cursor. The endpoint actually responds. Cursor caches MCP state aggressively, so a real restart matters.

ToolPiper is running. Menu bar icon, or curl http://127.0.0.1:9998/health. Connection refused means the app isn't open.
JSON is valid. Run the file through a linter or paste it into a JSON validator. A missing comma or stray quote is the most common cause of "server didn't load".
Cursor restarted. Quit through the app menu, not just close the window. Relaunch. Some Cursor builds need a full quit to re-read MCP config.
Endpoint responds. curl http://127.0.0.1:9998/mcp with appropriate JSON-RPC payload. A 404 or connection refused means the server isn't there.

If everything looks right but Cursor still doesn't see the tools, check Cursor's developer console (View → Toggle Developer Tools). MCP discovery errors show up there with diagnostic detail Cursor doesn't surface in the UI.

For setup on other editors, see MCP Setup on Mac.