---
title: "MCP Integration — ModelPiper"
description: "Model Context Protocol (MCP) server documentation for ToolPiper. Connect Claude Code, AI agents, and other MCP clients to local AI models."
canonical: "https://modelpiper.com/docs/mcp/"
---

# MCP Integration — ModelPiper

> Model Context Protocol (MCP) server documentation for ToolPiper. Connect Claude Code, AI agents, and other MCP clients to local AI models.

# MCP Server

Offline

ToolPiper is an MCP server — 147 tools and 5 resources that give AI coding assistants access to local inference, speech, vision, OCR, NLP, RAG, image/video processing, AX-powered browser automation, web scraping, PiperTest execution, programmatic video creation, outreach, macOS system actions, and OAuth. No cloud, no API keys.

## Install

Install ToolPiper, then add categories to your AI client. Each category is a focused set of tools — install only what you need to save up to 90% of AI context overhead. The MCP binary ships inside ToolPiper.app — nothing else to install.

`core`11 tools

LLM inference, TTS, STT, embeddings, OCR

```
claude mcp add toolpiper -- ~/.toolpiper/mcp --category core
```

`analysis`8 tools

Image/text analysis, RAG, upscaling

```
claude mcp add toolpiper -- ~/.toolpiper/mcp --category analysis
```

`browser`17 tools

Browser automation, scraping, assertions

```
claude mcp add toolpiper -- ~/.toolpiper/mcp --category browser
```

`testing`6 tools

PiperTest CRUD and execution

```
claude mcp add toolpiper -- ~/.toolpiper/mcp --category testing
```

`motion`5 tools

Pose estimation, stream processing

```
claude mcp add toolpiper -- ~/.toolpiper/mcp --category motion
```

`outreach`12 tools

GitHub, HN, Reddit, X, content queue

```
claude mcp add toolpiper -- ~/.toolpiper/mcp --category outreach
```

`system`29 tools

macOS system actions

```
claude mcp add toolpiper -- ~/.toolpiper/mcp --category system
```

`video`12 tools

Video creator pipeline

```
claude mcp add toolpiper -- ~/.toolpiper/mcp --category video
```

`oauth`4 tools

OAuth connection management

```
claude mcp add toolpiper -- ~/.toolpiper/mcp --category oauth
```

`full`147 tools

All categories — everything ToolPiper can do

```
claude mcp add toolpiper -- ~/.toolpiper/mcp
```

## Profiles

Profiles combine multiple categories for common workflows. Use `--profile` instead of listing categories individually.

`inference`11core

`automation`34core + browser + testing

`creative`35core + video + outreach

`full`147all categories

Example — web dev workflow (34 tools):

```
claude mcp add toolpiper -- ~/.toolpiper/mcp --profile automation
```

## Other Transports

The install commands above use Claude Code's CLI. For other clients, add `--category` or `--profile` to the `args` array:

### Cursor / Windsurf / Gemini Code

Add to `.mcp.json` in your project root:

```
{
  "mcpServers": {
    "toolpiper": {
      "type": "stdio",
      "command": "~/.toolpiper/mcp",
      "args": ["--category", "core,browser"]
    }
  }
}
```

### HTTP (Streamable HTTP)

For clients that support MCP over HTTP — no CLI middleman:

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

## Tools 147

Tool names are unprefixed — the MCP server namespace (`toolpiper`) provides branding and collision avoidance. Every tool includes annotations (`readOnlyHint`, `openWorldHint`).

### Core

11

`chat`read-onlyRun a prompt through a local LLM (llama.cpp or Apple Intelligence)

`transcribe`read-onlyTranscribe audio to text (FluidAudio or MLX Audio)

`speak`Convert text to speech and save as WAV

`voice_clone`Generate speech using a cloned voice from a reference audio sample

`embed`read-onlyGenerate vector embeddings (local model or Apple NL)

`ocr`read-onlyExtract text from images (Apple Vision, 18+ languages)

`models`read-onlyList available models with status and categories

`load_model`Load a model into memory (auto-downloads if needed)

`unload_model`Unload a model from memory to free RAM/VRAM

`download_model`Search HuggingFace and download GGUF/MLX model files

`status`read-onlySystem health — backends, GPU, RAM, license tier

### Apple Frameworks + RAG

8

`analyze_image`read-onlyApple Vision — classify, faces, barcodes, saliency, poses, and more

`analyze_text`read-onlyApple NLP — language, sentiment, entities, tokenize, lemmatize, POS

`rag_query`read-onlySemantic search across knowledge base collections (HNSW + BM25)

`rag_collections`read-onlyList RAG collections with chunk counts and indexing status

`rag_ingest`Re-index a RAG collection after adding new documents

`image_upscale`Upscale image 4x using CoreML super-resolution (Neural Engine)

`video_upscale`Upscale video 2x using PiperSR on Neural Engine — frame-by-frame, audio passthrough

`benchmark_upscale`read-onlyRun PiperSR 2x benchmark suite — tile, batch, full-frame, sustained, resolution sweep

### Browser Automation (AX Engine)

17

We built a custom Chrome DevTools Protocol (CDP) engine because Playwright MCP and chrome-devtools MCP weren't cutting it.

AX-native selectors`role:button:Sign In`, `role:form:Login > role:button:Submit`

Self-healingFuzzy AX match in ~5-15ms — no AI round-trip, no flaky CSS selectors

Mutation diffingEvery action returns what changed on the page — ~5 lines, not ~200

No dependenciesDirect CDP over WebSocket — no Playwright, no Puppeteer, no Node.js

Unique toolsWebAuthn virtual authenticator, Chrome native autofill, network interception with rule management

`browser_snapshot`read-onlyAX tree snapshot of browser page — auto-connects, optional navigation + screenshot

`browser_action`Click, fill, navigate, press, drag, upload — AX selectors, self-healing, mutation diff

`browser_assert`read-onlyAssert visible/hidden/text/url/count/attribute/console with polling + snapshot on failure

`browser_console`read-onlyConsole messages + optional network request logs for debugging

`browser_record`Record interactions with AX-enriched selectors and hierarchical scoping

`browser_manage`Connection lifecycle — status, pages, select/close/new tab, resize, dialog handling

`browser_eval`Execute JavaScript in the browser page and return the serialized result

`browser_network`Network traffic inspection — enable, list, get body, filter by URL or status

`browser_storage`Read/write cookies, localStorage, and sessionStorage

`browser_performance`Web Vitals tracing — LCP, FCP, CLS, TBT, JS heap, layout counts

`browser_coverage`JS and CSS code coverage measurement

`browser_intercept`Mock/intercept network requests — API stubbing, error simulation, offline testing

`browser_webauthn`Virtual authenticator for passkey/WebAuthn testing

`browser_autofill`Trigger Chrome native autofill on credit card and address fields

`browser_detect`read-onlyDetect frontend framework, meta-framework, CMS, and state libraries on a page

`scrape`read-onlyCDP web scraping — navigate, framework-aware readiness, 7 output formats (markdown, AX tree, etc.)

`youtube_transcript`read-onlyFetch transcript (captions) of a YouTube video

### PiperTest

6

`test_list`read-onlyList saved PiperTests with metadata (id, name, step count, last run status)

`test_get`read-onlyGet full PiperTest by ID with all steps, AX paths, and execution context

`test_save`Create or update a grouped PiperTest session — groups contain steps with action/assertion/mock

`test_delete`Delete a saved PiperTest by ID

`test_run`Execute grouped PiperTest via CDP at native speed (~10-50ms/step) with optional AX healing

`test_export`read-onlyExport PiperTest to Playwright or Cypress code — deterministic, no AI

### Pose Estimation + Stream Processing

5

`pose_detect`read-onlyDetect human body poses — skeleton image + keypoint coordinates, multiple topologies

`pose_formats`read-onlyList detection backends, renderers, and skeleton topologies

`pose_stream`Start real-time pose streaming WebSocket server (on-demand)

`stream_start`Start real-time stream processing — WebSocket frame source + processor (pose, OCR, etc.)

`stream_stop`Stop a running stream processing session

### Outreach

12

### macOS System Actions

29

### Video Creator

12

### OAuth

4

## Resources 5

Read-only data the AI can pull into context without calling a tool.

`toolpiper://status`Server health, version, loaded models, system resources

`toolpiper://models`Full model catalog with availability and categories

`toolpiper://backends`Backend status — which engines are running

`toolpiper://tests`Saved PiperTests with metadata

`toolpiper://categories`Tool categories, counts, and profiles for filtering

## How It Works

```
AI Client (Claude Code, Cursor, Windsurf, Gemini Code, etc.)
    ↓ JSON-RPC (stdio or HTTP)
~/.toolpiper/mcp [--category | --profile]    OR    POST localhost:9998/mcp
    ↓
ToolPiper.app (macOS, running)
    ↓
Backends (llama.cpp, FluidAudio, MLX Audio, Apple Intelligence, Vision, NLP, Pose, CDP, System Actions)
```

### Auth

The MCP binary reads ToolPiper's session key from disk on every request. Zero configuration — just works.

### Errors

If ToolPiper isn't running, every tool returns an install message pointing to modelpiper.com. ToolPiper's own errors (auth, model not loaded, etc.) are passed through verbatim.

### Annotations

Every tool has `readOnlyHint`, `openWorldHint`, and `idempotentHint` (where applicable) so AI clients can make informed decisions about tool usage.

### Filtering

Pass `--category` or `--profile` to the MCP binary to serve only the tools you need. Reduces per-message token overhead by up to 90%. Instructions are also trimmed to match.

### Prompts

5 workflow templates available via `prompts/list`: setup-model, audit-page, create-test, voice-over, research-topic. Each returns step-by-step instructions with the right tool sequence.

### Structured Output

8 tools return `structuredContent` (machine-readable JSON) alongside human-readable text — embed, ocr, models, rag\_query, rag\_collections, speak, voice\_clone, image\_upscale.