MCP and OAuth cover the two big audiences: AI editors and cloud accounts. The HTTP API covers everything else. If you can make an HTTP request from a Mac, you can call ToolPiper. That means shell scripts, Python tools, macOS Shortcuts, keyboard hotkeys, the browser extension, your own apps, and anything else that speaks HTTP.

What's the HTTP API for?

Anything that isn't an AI editor or a cloud account, but still needs to call ToolPiper's tools. A nightly shell script that summarizes yesterday's call recordings. A Shortcut that runs OCR on a screenshot. A hotkey that triggers push-to-talk dictation. The browser extension piping page content for analysis. All of them call the same HTTP endpoints.

Three patterns dominate:

  • Custom scripts. Shell, Python, Node, anything with HTTP support. You write the orchestration, ToolPiper provides the tools.
  • macOS automation surfaces. Shortcuts.app, hotkeys, and the push-to-talk system. These are macOS-native triggers that turn into HTTP calls to ToolPiper.
  • Browser extension. The MediaPiper extension uses the API to pipe page content from your browser to ToolPiper for analysis.

What does the API actually look like?

It's a JSON-over-HTTP REST API on http://127.0.0.1:9998. Endpoints map to tool categories: POST /chat, POST /audio/transcribe, POST /scrape, POST /vision/screenshot, etc. Bodies are JSON. Responses are JSON. Same over 300 tools as MCP, exposed as REST.

The API isn't an MCP-over-HTTP bridge. It predates MCP support in ToolPiper and is what MCP sits on top of internally. Both surfaces converge on the same tool implementations, but the wire format is different. MCP is JSON-RPC. The HTTP API is REST.

The endpoint shape, by category:

  • Inference. POST /chat, POST /audio/transcribe, POST /audio/speak, POST /vision/ocr, POST /text/embed.
  • Browser. POST /browser/launch, POST /browser/snapshot, POST /browser/action, etc.
  • System. POST /system/window/list, POST /system/input/type, POST /system/clipboard/read, etc.
  • Scraping. POST /scrape.
  • Vision. POST /vision/screenshot, POST /vision/color_pick.
  • Files. POST /file/read, POST /file/write, etc.

Each endpoint has a JSON schema for the request body, and the response is JSON with the tool's output. Errors come back as HTTP 4xx/5xx with JSON error bodies. Standard REST conventions throughout.

How does authentication work?

Loopback-only by default. Requests from 127.0.0.1 are accepted without authentication. If you enable LAN access (for connecting from another device on your network), ToolPiper issues tp_lan tokens that clients must include in an Authorization: Bearer header on every request.

This split matters. Loopback requests originate on the same machine as ToolPiper. macOS already controls what can run on your Mac, and ToolPiper trusts that. A request from a different machine on your network is qualitatively different. ToolPiper requires explicit authentication for those.

To enable LAN access:

  1. Open ToolPiper Preferences -> Network.
  2. Toggle "Allow LAN access".
  3. ToolPiper generates a tp_lan_* token. Copy it.
  4. Configure your client (the Mac, iPhone, or other device) to include the token in an Authorization: Bearer tp_lan_... header.

Tokens rotate on demand from the same preferences pane. Old tokens are invalidated immediately.

Where do I start?

Pick the caller you're trying to wire up. Custom scripts, Shortcuts and hotkeys, and the browser extension each have a dedicated guide with worked examples.

  • HTTP API guide. Endpoint reference, request/response shapes, authentication details, code samples in shell and Python.
  • Shortcuts and hotkeys guide. How to call ToolPiper from Shortcuts.app's Get Contents of URL action, how to wire keyboard hotkeys, and how ToolPiper's built-in push-to-talk dictation runs this same path internally.
  • Browser extension guide. Installing MediaPiper, what page content it sends to ToolPiper, and how to build a custom extension that uses the same API surface.

For higher-level integrations (AI editors, cloud accounts), see MCP Setup on Mac and Connect ToolPiper to Your Cloud Accounts via OAuth on Mac.

Why use the HTTP API instead of MCP?

Because MCP assumes an AI editor as the orchestrator. The HTTP API doesn't. If you want to wire a script, a hotkey, or a Shortcut where you control the orchestration logic, the HTTP API is the lighter and more direct path.

MCP is the right choice when you want an AI model to decide which tool to call. The HTTP API is the right choice when you already know which tool you want and just need to call it. A shell script that calls POST /vision/screenshot + POST /vision/ocr + POST /chat in sequence does its job in three lines. The same flow as MCP would require an AI editor in the loop, which is overkill if you're trying to script something deterministic.

You can mix both. Use MCP from your editor for exploratory work. Use the HTTP API from scripts for repeated, scripted automation. Same tools underneath either way.