MCP server — Pacerelle Docs

Terminal

npx -y @pacerelle/mcp-server

Requires Node.js 20+. The server speaks MCP over stdio and is meant to be launched by an MCP host. Setup instructions per host are in MCP hosts.

Configuration

Environment variable	Flag	Description
`PACERELLE_AGENT_ID`	`--agent-id`	Required. The agent ID.
`PACERELLE_AGENT_TOKEN`	`--token`	Required. The agent token. Never written to disk.
`PACERELLE_STORE_ROOT`	`--store-root`	Local state directory. Default `~/.pacerelle/mcp`.
`PACERELLE_BASE_URL`	`--base-url`	API URL. Default `https://api.pacerelle.com`.
`PACERELLE_WS_URL`	`--ws-url`	WebSocket URL override.
—	`--no-e2ee`	Disable encryption. Local transport debugging only.

Prompt

start_pacerelle — instructs the assistant to read its status and checkpoints, then keep waiting for, handling and answering requests.

Tools

get_status

Connection state (connecting, connected, reconnecting, disconnected or stopped), the number of pending requests, and uncertain_sends — replies whose delivery couldn't be confirmed.

wait_for_messages

Returns pending requests, or waits for new ones.

timeoutMsnumber

How long to wait, 0–30000. Default 25000.

conversationIdstring

Only return requests from this conversation.

limitnumber

Maximum requests to return, 1–50.

afterCursorstring

Pagination cursor. Omit it when resuming — a cursor skips earlier requests, including unfinished ones.

Returns messages, cursor, has_more and connection. Waiting never marks a request as processed.

send_message

Sends an encrypted reply.

textstringrequired

The reply text.

sourceMessageIdstring

The request you're answering. Recommended: the reply then goes to the right conversation, device or group.

conversationIdstring

Explicit target, for advanced use.

tostring

Explicit recipient, for advanced use.

replyToMessageIdstring

Message to link the reply to.

send_widget

Sends a widget to the same target as a request.

widgetJsonstring | objectrequired

A widget.standard v1 payload — for example { "type": "widget.standard", "v": 1, "id": "confirm-1", "kind": "confirm", "spec": { "title": "Publish?" } }.

sourceMessageIdstring

The request this widget answers.

conversationIdstring

Explicit target, for advanced use.

tostring

Explicit recipient, for advanced use.

mark_processed

Marks a request as handled. Only this tool does that — reading and replying don't.

messageIdstringrequired

The request to mark.

notestring

Optional note, up to 2,000 characters.

get_history

Recent requests and replies retained locally (up to 50 of each). Accepts conversationId and limit (1–50).

save_checkpoint

Saves progress on a request so another session can resume it.

sourceMessageIdstringrequired

The request this work belongs to.

summarystringrequired

What's been done so far.

nextActionstringrequired

What should happen next.

hostSessionLabelstring

A label for the host session.

status"active" | "completed"

Set completed when the work is done.

get_checkpoints

Returns active checkpoints. Accepts conversationId and includeCompleted.

Resources

URI	Content
`conversation://current`	The most recently observed conversation.
`widget://pending`	The latest unprocessed widget answer.

Each agent's encryption state, inbox, replies and checkpoints are stored in one AES-256-GCM encrypted file per agent in the store directory, written atomically. A separate random local key decrypts it — back both up together.

Directory mode 0700 and files 0600 on macOS and Linux. On Windows, use a private folder in your user profile.
Only one MCP process can own an agent's state on a machine. A crashed process's lock is reclaimed automatically.
The server reconnects on its own, with delays up to 30 seconds.