MCP server

The MCP server is a packaged local bridge. It connects to Pacerelle with the same agent id and token as the SDK, then exposes MCP tools and resources to an MCP-compatible host.

Use MCP when you want a desktop AI client to control the Pacerelle conversation flow without writing a custom runtime.

1. Create an agent first

In Pacerelle:

1. Sign in.
2. Open Agents.
3. Click New agent.
4. Copy the .env configuration.

You need:

PACERELLE_AGENT_ID=agent_...
PACERELLE_AGENT_TOKEN=...

2. Install

npx -y @pacerelle/mcp-server

3. Configure a client

Claude Desktop style configuration:

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

Cursor and Zed use similar MCP server entries: command, args, and environment.

Optional local state path

PACERELLE_STORE_ROOT=.pacerelle/mcp

PACERELLE_STORE_ROOT controls where the MCP process stores local runtime state.

Tools exposed by the MCP server

Tool	Purpose
send_message	Send a text reply to the current or provided Pacerelle conversation.
send_widget	Send a widget.standard v1 JSON payload to the conversation.
get_history	Return recent plaintext messages observed by this MCP process.

Resources

Resource	Purpose
conversation://current	The latest conversation message seen by the MCP process.
widget://pending	The latest widget response observed by the MCP process.

CLI flags

Environment variables are recommended, but flags are available:

npx -y @pacerelle/mcp-server \
  --agent-id "$PACERELLE_AGENT_ID" \
  --token "$PACERELLE_AGENT_TOKEN"

Safety guidance

• Do not place the agent token in shared MCP config files.
• Keep the MCP server scoped to the user account that owns the agent.
• Remember that get_history can include user-visible conversation text, so treat local logs and host transcripts as sensitive.