MCP hosts — Pacerelle Docs

The Pacerelle MCP server gives an assistant running in an MCP host an encrypted inbox. You write to it from the Pacerelle app; the assistant reads your requests with MCP tools, does the work with its usual tools, and replies — no code to write.

The host must keep the assistant running

Installing the server doesn't wake your assistant up by itself. The assistant has to be in a session that keeps calling wait_for_messages. Hosts may stop at a turn limit, ask for approvals or end the session. For an agent that runs unattended 24/7, use the JavaScript or Python SDK instead.

Set it up

Create an agent

In the Pacerelle app, open Agents → Connect an agent and copy the agent ID and token. See Manage your agents.

Add the server to your host

The server runs locally with npx (Node.js 20+). Add it with your agent's values:

claude_desktop_config.json

{
  "mcpServers": {
    "pacerelle": {
      "command": "npx",
      "args": ["-y", "@pacerelle/mcp-server"],
      "env": {
        "PACERELLE_AGENT_ID": "agent_...",
        "PACERELLE_AGENT_TOKEN": "..."
      }
    }
  }
}

Restart the host so it picks up the new server. Other hosts work too — use their MCP configuration format with the same command, arguments and variables.

Start the listening loop

In a new conversation with the assistant, select the start_pacerelle prompt, or ask:

Start or resume my Pacerelle work. Read get_status and get_checkpoints, then wait_for_messages without a cursor. Handle each authorized request, reply using its sourceMessageId, and mark_processed after handling it. Save a checkpoint before an interruption. Keep listening while this session can continue; tell me if listening stops.

Test from your phone

Send a message to the agent in Pacerelle and check that a readable reply comes back before you leave your computer. Keep the computer, the host and the assistant session running.

What the assistant can do

The server exposes eight tools. The full details are in the MCP server reference.

Tool	Purpose
`get_status`	Connection state, pending requests, uncertain sends.
`wait_for_messages`	Return pending requests, or wait up to 30 s for new ones.
`send_message`	Send an encrypted reply to a request.
`send_widget`	Send a widget such as a confirmation or a choice.
`mark_processed`	Mark a request as handled. Reading doesn't do this.
`get_history`	Recent requests and replies kept locally.
`save_checkpoint`	Save progress on a request before an interruption.
`get_checkpoints`	Resume saved work in a new session.

Resume in another session

Before a session ends, the assistant can call save_checkpoint with a summary and the next action. The next session reads get_checkpoints, calls wait_for_messages and picks up where it left off — without you pasting a transcript. Checkpoints hold only what the assistant saved explicitly.

Where state is kept

The server stores the agent's encryption state, inbox, replies and checkpoints in an encrypted file under ~/.pacerelle/mcp (override with PACERELLE_STORE_ROOT). Tokens are never written to disk.

Only one host at a time can use an agent's state on a machine. Close the server in the old host before opening it in another.
Back up the store directory as a whole: the state file and its local key go together.

Good to know

Your host's own permission rules still apply to everything the assistant does.
A submitted reply means it was handed to the relay — check the conversation before repeating something consequential.
Pending requests stay in the inbox until the assistant marks them processed.