--- title: "Connect ToolPiper to Scripts, Shortcuts, and System Triggers on Mac" description: "ToolPiper serves a local HTTP API on 127.0.0.1:9998. Hit it from shell scripts, macOS Shortcuts, hotkeys, or the browser extension. Loopback only." date: 2026-05-13 author: "Ben Racicot" tags: ["HTTP API", "macOS Shortcuts", "Hotkeys", "Browser Extension", "Privacy", "macOS", "Automation"] type: "article" canonical: "https://modelpiper.com/blog/connect-toolpiper-scripts-system/" --- # Connect ToolPiper to Scripts, Shortcuts, and System Triggers on Mac > ToolPiper serves a local HTTP API on 127.0.0.1:9998. Hit it from shell scripts, macOS Shortcuts, hotkeys, or the browser extension. Loopback only. ## TL;DR ToolPiper's local HTTP API at http://127.0.0.1:9998 is the third connection surface, alongside MCP and OAuth. Anything on your Mac that can make an HTTP request can call any of ToolPiper's over 300 tools. Shell scripts, Python, Node, macOS Shortcuts, hotkey-launched binaries, and the browser extension all use the same endpoint set. 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**](/blog/toolpiper-http-api). Endpoint reference, request/response shapes, authentication details, code samples in shell and Python. - [**Shortcuts and hotkeys guide**](/blog/toolpiper-shortcuts-hotkeys). 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**](/blog/toolpiper-browser-extension). 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](/blog/mcp-setup-guide-mac) and [Connect ToolPiper to Your Cloud Accounts via OAuth on Mac](/blog/connect-toolpiper-oauth). ## 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. ## FAQ ### Is the HTTP API documented? Yes. Every endpoint has a request/response schema. The full reference is in the [HTTP API guide](/blog/toolpiper-http-api), with example curl commands and Python snippets for the most common workflows. ### Can a script running as a different user access ToolPiper? Loopback-only and not LAN-enabled: only processes on the same Mac as ToolPiper can reach it, regardless of user. LAN-enabled: any process that can reach port 9998 over the network and has a valid `tp_lan` token. Within the same Mac, OS-level access controls (sandboxing, App Sandbox entitlements) still apply. ### Does the HTTP API have a websocket version? Yes for specific use cases. Pose streaming, log streaming, and audio chunking use websockets where the request/response shape requires it. Most tools use plain REST. ### What's the relationship between the HTTP API and MCP? MCP is layered on top of the HTTP API. The MCP server dispatches tool calls in-process to the same handlers the HTTP API uses. They share implementations, error semantics, and tool capabilities. The wire formats differ (MCP is JSON-RPC, HTTP is REST), but the behavior is identical. ### How do I see the available endpoints? The catalog is in the HTTP API guide. ToolPiper also exposes a discovery endpoint at `GET /v1/openapi.json` that returns the full OpenAPI spec, so tools that consume OpenAPI (like API clients or codegen) can introspect it.