ToolPiper answers HTTP on 127.0.0.1:9998 in two ways. The REST API under /v1 covers the OpenAI-compatible core (chat, models, embeddings, speech) and the app's own features. The MCP endpoint at /mcp reaches every tool by name, including the ones with no REST route of their own. Shell, Python, Node, Swift: anything with HTTP support can call either.
What's the base URL and shape?
Base URL is http://127.0.0.1:9998. REST routes live under /v1 and take and return JSON; the OpenAI-compatible ones use OpenAI's request and response shapes. Every /v1 call needs an Authorization: Bearer tp_... header. The full route list is the OpenAPI spec at GET /v1/openapi.json.
A working example with curl, calling the OpenAI-compatible chat route against a local model. Replace the model id with one from GET /v1/models:
curl -s http://127.0.0.1:9998/v1/chat/completions \
-H "Authorization: Bearer $TOOLPIPER_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"model": "<model-id>",
"messages": [
{"role": "user", "content": "Summarize the MCP spec in one sentence."}
]
}'The answer comes back in OpenAI's chat completion shape, with the text at choices[0].message.content. Send "stream": true to receive it as Server-Sent Events instead.
How do I authenticate?
Create a developer token in ToolPiper under Security, pick its scopes, and send it as Authorization: Bearer tp_<64 hex>. Developer tokens are free on every tier. A /v1 call without one returns 401, even from your own Mac.
Pick scopes for the job: chat for inference routes, tools:read for listings such as /v1/models, tools:exec for routes that run a tool against the Mac. A call outside the token's scopes returns 403 and names the missing scope. Keep the token in an environment variable rather than in a script you commit, and revoke it from the same pane when you no longer need it.
For a quick local script there is also the launch token: ToolPiper writes a fresh one to ~/Library/Application Support/ToolPiper/.toolpiper-token (file mode 0600) every time it starts. It carries every scope and changes on each launch, so read it at run time rather than copying it anywhere. A developer token is the better choice for anything that lasts.
From another device on your network, the same header applies, with the Mac's address in place of 127.0.0.1:
curl -s http://192.168.1.10:9998/v1/chat/completions \
-H 'Authorization: Bearer tp_abc123...' \
-H 'Content-Type: application/json' \
-d '{ "model": "<model-id>", "messages": [{"role": "user", "content": "Hello"}] }'You can see and control who is connected without leaving the app. The Connected Apps pane lists every authenticated client as a labeled row showing its MCP-tools access state, and a one-click revoke kills that bearer immediately. The row stays visible, marked revoked, so state is never hidden. The Tool governance overlay is restrict-only: you can deny specific tools (say, system_run_command) for every client, or flip the built-in tool marketplace from open browse to an explicit allow-list of servers and tools. It only ever narrows what a tier already permits, never widens it. Today that overlay is a per-device, locally-edited policy; the same shape is built so an organization can push it later (controls lock with a "Managed by your organization" badge), but org-managed governance is planned, not a shipping admin console yet.
How do I call a tool that has no REST route?
Through /mcp. It speaks MCP's Streamable HTTP: send initialize, keep the Mcp-Session-Id header it returns, then call any tool by name with tools/call. Loopback callers reach /mcp without a token.
BASE=http://127.0.0.1:9998/mcp
H='Accept: application/json, text/event-stream'
SID=$(curl -s -D - -o /dev/null -X POST $BASE -H "$H" \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-script","version":"1"}}}' \
| awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}' | tr -d '\r')
curl -s -X POST $BASE -H "$H" -H "Mcp-Session-Id: $SID" \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'
curl -s -X POST $BASE -H "$H" -H "Mcp-Session-Id: $SID" \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"system_uptime","arguments":{}}}'The result is a JSON-RPC response whose result.content holds the tool's output, usually plain text. tools/list returns every tool with its input schema. Tier rules apply here as everywhere: a tool above your plan answers with a short sentence naming the plan it needs rather than running.
How do I find the available endpoints?
The OpenAPI spec at GET /v1/openapi.json lists the REST routes with their request and response schemas; it needs no token. Load it into Postman, Insomnia, Bruno or a code generator. For tools, tools/list on /mcp is the catalog.
A few REST routes you will reach for first:
- OpenAI-compatible core.
GET /v1/models,POST /v1/chat/completions,POST /v1/embeddings,POST /v1/audio/transcriptions,POST /v1/audio/speech. - Models.
POST /v1/engine/load,POST /v1/engine/unload,GET /v1/models/installed. - Liveness.
GET /health, with no token.
What does a real script look like?
A Python script that summarizes a text file with a local model: one authenticated call to the OpenAI-compatible route.
import os, sys, requests
BASE = "http://127.0.0.1:9998/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['TOOLPIPER_TOKEN']}"}
text = open(sys.argv[1]).read()
r = requests.post(f"{BASE}/chat/completions", headers=HEADERS, json={
"model": os.environ["TOOLPIPER_MODEL"],
"messages": [
{"role": "system", "content": "Summarize in one sentence."},
{"role": "user", "content": text},
],
})
r.raise_for_status()
print(r.json()["choices"][0]["message"]["content"])Because the route is OpenAI-compatible, the official OpenAI SDKs work too: set the base URL to http://127.0.0.1:9998/v1 and pass the developer token as the API key.
How does the HTTP API relate to MCP?
They are two doors into the same app. MCP tool calls dispatch in-process to the same handlers the REST routes use, so behavior matches. REST is best when you know the call you want; MCP is best when a model decides which tool to use, and for tools with no REST route.
Both work concurrently against the same ToolPiper instance.
What happens when ToolPiper isn't running?
HTTP requests return connection refused. The API is hosted inside the ToolPiper app, not as a separate daemon. ToolPiper launches at login by default (a toggle in its Settings turns that off), and scripts should still check ToolPiper's /health endpoint first.
# Sanity check before running a script
if ! curl -sf http://127.0.0.1:9998/health > /dev/null; then
echo "ToolPiper isn't running; launching..."
open -a ToolPiper
sleep 3
fiThe /health endpoint returns JSON with "status": "ok", the version and build number, and the uptime. It needs no token and is designed for liveness checks.
