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