---
title: "Claude Code MCP Setup: Add ToolPiper for 300+ Local Tools on Mac"
description: "Connect Claude Code to ToolPiper's local MCP server. One CLI command, over 300 tools, no cloud. Covers user vs project scope, verification, and common gotchas."
date: 2026-05-09
author: "Ben Racicot"
tags: ["Claude Code", "MCP", "Model Context Protocol", "Setup Guide", "Privacy", "macOS", "Developer Tools"]
type: "article"
canonical: "https://modelpiper.com/blog/claude-code-mcp-setup-toolpiper/"
---

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

> Connect Claude Code to ToolPiper's local MCP server. One CLI command, over 300 tools, no cloud. Covers user vs project scope, verification, and common gotchas.

## TL;DR

Run claude mcp add -s user --transport http toolpiper http://127.0.0.1:9998/mcp from any terminal. Restart your Claude Code session. ToolPiper's over 300 tools (local LLM chat, browser automation, screen capture, system control, web scraping, video, audio) appear in every new chat. Loopback-only, no cloud.

You've got ToolPiper running. You want Claude Code to start using its over 300 tools. This is the one-line setup, plus the gotchas that explain why it sometimes looks like nothing happened.

## Why connect Claude Code to ToolPiper?

Claude Code on its own can read files, run shell commands, and talk to Claude. ToolPiper adds over 300 tools the model can call: local LLM chat, browser automation, screen capture, audio transcription, system control, web scraping, video production, and more. None of them require a network round-trip beyond the editor itself.

The setup adds ToolPiper as an HTTP MCP server inside Claude Code's MCP registry. Once registered, every new Claude Code session sees ToolPiper's tools alongside the built-in ones. The model picks tools based on the conversation, same as always.

One concrete example: _"take a screenshot, OCR the visible text, then summarize what's on screen."_ Claude Code without ToolPiper can't do this. With ToolPiper, the model calls `vision_screenshot`, then `vision_ocr` on the result, then summarizes. All from the same prompt.

## How do I add ToolPiper to Claude Code?

Run `claude mcp add --transport http toolpiper http://127.0.0.1:9998/mcp`. Add `-s user` if you want the registration available in every project. Restart your Claude Code session to pick up the new tools.

The full command, with the scope flag included:

```
claude mcp add -s user --transport http toolpiper http://127.0.0.1:9998/mcp
```

Three parts to it:

-   `-s user`. Scope. Without it, the registration only applies to the current project directory. With it, every Claude Code session you start on this Mac sees ToolPiper.
-   `--transport http`. Transport. ToolPiper exposes MCP over HTTP at `http://127.0.0.1:9998/mcp`. The default transport is stdio, which expects a process to spawn. Skip this flag and you'll see "command not found".
-   `toolpiper`. Server name. Shows up in tool listings as the prefix on tool names.

Run the command, then start a new Claude Code session. The previous session was loaded before the MCP registration, so it doesn't know about ToolPiper. The next one will.

## How do I verify the connection works?

Run `claude mcp list`. ToolPiper should appear with status `✓ Connected`. If it shows as failed or missing, ToolPiper either isn't running or the registration didn't take.

Sample output of a working setup:

```
$ claude mcp list
Checking MCP server health...
toolpiper: http://127.0.0.1:9998/mcp (HTTP) - ✓ Connected
```

For an even tighter check, ask Claude Code something only ToolPiper can do. Try _"take a screenshot of my screen"_ in a chat. If the model calls `vision_screenshot` and returns the result, the setup is wired correctly.

## What does -s user vs project scope mean?

Claude Code stores MCP registrations in two places. A project-local `.mcp.json` file checked into the repo, and a user-level config in `~/.claude.json`. `-s user` writes to the user-level config so every project sees ToolPiper. Without it, only the current project sees it.

Three reasons to use `-s user`:

-   You want ToolPiper available everywhere by default, without re-running the add command in each new project.
-   You don't want to commit ToolPiper into `.mcp.json` in shared repositories. That can leak machine-specific config to teammates who don't have ToolPiper installed.
-   You're setting up a brand-new Mac and want to be done with MCP setup permanently.

One reason not to: you want ToolPiper available in specific projects but not others. In that case, run the command without `-s user` from each project directory you want it in.

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

Four checks in order. ToolPiper is running. The MCP registration succeeded. You restarted Claude Code. The HTTP endpoint actually responds.

The first three almost always cover it. Run through them:

1.  ToolPiper is running. Look for the ToolPiper icon in your menu bar. If it's not there, launch the app. The MCP server only exists while the app does.
2.  MCP registration succeeded. Run `claude mcp list`. ToolPiper should appear. If it doesn't, re-run the add command. If the command errors with "already exists", remove it with `claude mcp remove toolpiper` and add it again.
3.  Claude Code restarted. Exit the current session. Start a fresh one from the same directory. The new session re-reads MCP config.
4.  HTTP endpoint responds. `curl http://127.0.0.1:9998/health`. A JSON response with `"status": "ok"` means the server is alive. Connection refused means ToolPiper isn't actually running, even if the menu bar icon suggests otherwise.

If all four pass and Claude Code still doesn't see the tools, check ToolPiper's logs. `curl "http://127.0.0.1:9998/logs?level=error&limit=20"` dumps the last 20 errors. MCP discovery failures show up there with stack traces.

For full setup options across other editors, see [MCP Setup on Mac](/blog/mcp-setup-guide-mac).

## FAQ

### How do I remove ToolPiper from Claude Code?

Run `claude mcp remove toolpiper` from any Claude Code session. The registration is deleted but ToolPiper itself keeps running for any other clients (Cursor, Claude Desktop, your scripts). To remove a user-scope registration specifically, use `claude mcp remove -s user toolpiper`.

### Does ToolPiper work with Claude Code's plan mode and subagents?

Yes. ToolPiper tools are available wherever Claude Code can call MCP tools. Regular chat, /plan mode, /agents, custom slash commands. The model in each context decides whether to invoke a tool based on the prompt and the tool's description.

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

Yes. Claude Code lets you register as many MCP servers as you want, and the model sees the combined tool catalog. Common pairings: ToolPiper + Playwright MCP, ToolPiper + GitHub MCP, ToolPiper + a project-specific filesystem MCP. The names need to be unique (you can't have two servers named "toolpiper"), but otherwise there's no conflict.

### Does Claude Code call ToolPiper tools automatically or do I have to ask?

The model decides. When the conversation calls for a tool ToolPiper exposes, the model invokes it. You don't have to name the tool. A prompt like "take a screenshot and tell me what's on it" triggers `vision_screenshot` and `vision_ocr` automatically. You can also force a specific tool by naming it: "call vision\_screenshot".

### Do I need to re-register ToolPiper after a ToolPiper update?

No. The registration points at the HTTP endpoint, not at a binary or version. ToolPiper updates in place. Tool definitions might change (new tools added, schemas refined), but Claude Code re-discovers them on the next session start. No manual re-registration needed.