---
title: "Cursor MCP Setup: Add ToolPiper for 300+ Local Tools on Mac"
description: "Connect Cursor to ToolPiper's local MCP server with a single JSON snippet. Global or per-project, over 300 local tools, no cloud round-trip."
date: 2026-05-10
author: "Ben Racicot"
tags: ["Cursor", "MCP", "Model Context Protocol", "Setup Guide", "Privacy", "macOS", "Developer Tools"]
type: "article"
canonical: "https://modelpiper.com/blog/cursor-mcp-setup-toolpiper/"
---

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

> Connect Cursor to ToolPiper's local MCP server with a single JSON snippet. Global or per-project, over 300 local tools, no cloud round-trip.

## TL;DR

Open ~/.cursor/mcp.json (or .cursor/mcp.json inside a project), add a toolpiper entry pointing at http://127.0.0.1:9998/mcp with type http, restart Cursor. The agent in every chat sees over 300 ToolPiper tools alongside Cursor's built-ins.

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:

1.  Edit the file. `~/.cursor/mcp.json` for global, `.cursor/mcp.json` for per-project.
2.  Save. Cursor doesn't watch the file. Saving alone won't trigger a reload.
3.  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.

1.  ToolPiper is running. Menu bar icon, or `curl http://127.0.0.1:9998/health`. Connection refused means the app isn't open.
2.  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".
3.  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.
4.  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](/blog/mcp-setup-guide-mac).

## FAQ

### 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.