---
title: "Claude Desktop MCP Setup on Mac: Add ToolPiper for over 450 Local Tools"
description: "Connect Claude Desktop to ToolPiper's local MCP server on macOS through a stdio bridge in claude_desktop_config.json, then fully relaunch the app."
date: 2026-05-11
updated: 2026-09-22
author: "Ben Racicot"
tags: ["Claude Desktop", "MCP", "Model Context Protocol", "Setup Guide", "Privacy", "macOS", "Anthropic"]
type: "article"
canonical: "https://modelpiper.com/blog/claude-desktop-mcp-setup-mac"
---

# Claude Desktop MCP Setup on Mac: Add ToolPiper for over 450 Local Tools

> Connect Claude Desktop to ToolPiper's local MCP server on macOS through a stdio bridge in claude_desktop_config.json, then fully relaunch the app.

## TL;DR

Claude Desktop launches local MCP servers over stdio, so ToolPiper connects through a small bridge: add a toolpiper entry to ~/Library/Application Support/Claude/claude_desktop_config.json that runs npx mcp-remote against http://127.0.0.1:9998/mcp, then fully quit and relaunch Claude Desktop. Window close isn't enough.

Claude Desktop was the first MCP client Anthropic shipped, and it still connects to local servers one way: it launches them as processes and talks to them over stdio. ToolPiper serves MCP over Streamable HTTP at `http://127.0.0.1:9998/mcp` and no longer ships a stdio launcher, so the connection goes through a small stdio-to-HTTP bridge. This guide covers the bridge entry in `claude_desktop_config.json`, a full app relaunch (not just a window close), and the verification that confirms it worked.

## Does Claude Desktop support HTTP MCP servers?

Not for a server on your own Mac. Claude Desktop's local servers are stdio processes it launches from `claude_desktop_config.json`. Its remote connectors are reached from Anthropic's cloud, which cannot see `127.0.0.1` on your Mac. So a local HTTP server like ToolPiper needs a bridge: a stdio process that relays to the HTTP endpoint.

The bridge used here is [`mcp-remote`](https://github.com/geelen/mcp-remote), an open source npm package. It needs Node.js 18 or newer, and `npx` fetches it on first run. A ToolPiper extension for Claude Desktop is being prepared to replace this step; until it is published, the bridge is the way in.

## How do I add ToolPiper to Claude Desktop?

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`. Add a `toolpiper` entry under `mcpServers` that runs `mcp-remote` against `http://127.0.0.1:9998/mcp`. Quit Claude Desktop fully (Cmd-Q, not window close), then relaunch.

The JSON:

```
{
  "mcpServers": {
    "toolpiper": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:9998/mcp",
        "--allow-http",
        "--transport",
        "http-only"
      ]
    }
  }
}
```

`--allow-http` lets the bridge use plain HTTP, which is fine here because the traffic never leaves your Mac. `--transport http-only` keeps it on Streamable HTTP rather than falling back to the legacy SSE transport.

Steps:

1.  Locate the config file. `~/Library/Application Support/Claude/claude_desktop_config.json`. If it doesn't exist yet, create it with the JSON above. Claude Desktop reads it on launch.
2.  Add the entry. If `mcpServers` already has other servers, add `toolpiper` alongside them. Otherwise create the whole object.
3.  Quit Claude Desktop fully. Cmd-Q, or use the menu's Quit Claude option. Closing the window keeps the app running and your changes won't load.
4.  Relaunch. Open Claude Desktop from Applications or Spotlight.

## How do I verify the connection worked?

Open a new chat and check the tools menu in the composer. ToolPiper should appear as a tool source. If it doesn't, the config file has an error, Node.js is missing, or ToolPiper isn't running.

The Developer settings (Claude -> Settings -> Developer) show each MCP server's status and let you open its log, which is where a bridge error shows up.

End-to-end test with a free tool: _"Check ToolPiper's system status and tell me which models are loaded."_ If Claude calls `system_status` and reports back, ToolPiper is wired correctly.

## Why is a full relaunch necessary?

Claude Desktop reads `claude_desktop_config.json` only at process start. Closing the main window doesn't terminate the process. The app stays running in the background, holding the previous MCP state. A full Cmd-Q (or Force Quit) ends the process. The next launch reads the new config.

This catches more setups than the JSON syntax does. If you saved the file and reopened the Claude Desktop window expecting to see ToolPiper, you'll see no change. The process never restarted. Force Quit from the Apple menu's "Force Quit Applications" panel or run `killall Claude` in Terminal if Cmd-Q doesn't work.

## Do I need an API key for this?

No. The config above has no token because the bridge connects over loopback (`127.0.0.1:9998`), and ToolPiper trusts loopback at the socket level. On each launch it mints a short-lived bearer token at `~/Library/Application Support/ToolPiper/.toolpiper-token` (mode 0600, rotated every launch), so local clients just work with nothing to paste.

Off-machine clients are different. A LAN device or a PiperMesh peer must send a scoped `Bearer tp_<64 hex>` token with the right audience; those 64-char CSPRNG tokens never get written into `~/.claude/` or any config you don't control. Inside ToolPiper, the Connected Apps pane lists every authenticated client as a labelable row with its tool-access state and a one-click revoke that kills the bearer instantly and leaves the row visible as revoked. A separate restrict-only governance overlay lets you deny specific tools (say, `system_run_command`) for all clients or flip the tool marketplace from open browse to an explicit allow-list. Governance is per-device and locally edited today, with the same policy shape built so an organization can push it later (it locks behind a "Managed by your organization" badge when they do). It's not an enterprise SSO console yet, but the per-device controls are live now.

## What if Claude Desktop can't see ToolPiper?

Five checks. ToolPiper is running. Node.js is installed. The JSON is valid. Claude Desktop was fully relaunched. The bridge log shows no error.

1.  ToolPiper running. `curl http://127.0.0.1:9998/health` returns JSON with `"status": "ok"`.
2.  Node.js installed. `node --version` in Terminal prints 18 or newer. Without it, `npx` cannot start the bridge.
3.  JSON valid. Validate the file (paste into `python3 -m json.tool` or any JSON validator). A trailing comma or stray quote kills the entire config silently.
4.  Full relaunch done. Cmd-Q, then relaunch. Window close isn't enough.
5.  Bridge log. Claude -> Settings -> Developer shows the server's state and log. A connection error there with ToolPiper running usually means a typo in the URL.

For setup in other MCP clients, most of which connect to the HTTP endpoint directly, see [MCP Setup on Mac](/blog/mcp-setup-guide-mac).

## FAQ

### Where is Claude Desktop's config file on Mac?

`~/Library/Application Support/Claude/claude_desktop_config.json`. The folder might not exist if you've never customized Claude Desktop before; create it if needed.

### Why does Claude Desktop need a bridge for ToolPiper?

Claude Desktop launches local MCP servers as stdio processes, and its remote connectors run from Anthropic's cloud, which cannot reach `127.0.0.1` on your Mac. ToolPiper serves MCP over Streamable HTTP only, so a stdio bridge such as `mcp-remote` sits in between: Claude Desktop launches the bridge, and the bridge relays to `http://127.0.0.1:9998/mcp`.

### Do I need to register ToolPiper in Claude Desktop's Developer settings UI?

No. The JSON config is the single source of truth. The Developer settings UI displays the current MCP state but doesn't override the config file. Edit the file, restart, and the settings UI reflects the new state.

### Why does Claude Desktop need a full Cmd-Q instead of a window close?

On macOS, closing the window doesn't quit the app. The process stays alive and holds the previous MCP server state in memory. Claude Desktop reads `claude_desktop_config.json` only at process start. Cmd-Q (or Force Quit) terminates the process. The next launch loads the new config.

### Can I use ToolPiper alongside other MCP servers in Claude Desktop?

Yes. Add as many entries as you want under `mcpServers`. Claude Desktop combines them into a single tool catalog the model sees. The names need to be unique.
