paperclip-mcp

MCP server for the Paperclip AI agent orchestration platform, built for the human operator: run your company of agents from Claude Code, Claude Desktop or any MCP client.

Exposes the Paperclip REST API (v0.3.x, 2026-09) as 95 Model Context Protocol tools: issues, agents, goals, projects, approvals, costs and budgets, routines, decisions, pipelines and the attention feed.

Official MCP server vs this one. Paperclip ships @paperclipai/mcp-server (TypeScript, stdio only, ~45 paperclipXxx tools) aimed at agents running inside a heartbeat. paperclip-mcp is the Python, HTTP-or-stdio server for the board operator: it adds wake/pause/resume, hiring, budgets, cost breakdowns, routines, decisions, pipelines and the attention feed, and understands board API keys. Use the official one for agents, this one for yourself.

---

Tools

Issue ids accept either the UUID or the human identifier (PAP-42). Every tool docstring states which credential it needs.

---

Requirements

• Python 3.10+
• A running Paperclip instance (tested against main @ 2026-09-13, package version 0.3.1 / release 2026.831)
• A board API key (recommended) or an agent API key — see Credentials

---

Installation

git clone https://github.com/wizarck/paperclip-mcp
cd paperclip-mcp
pip install -e .          # or: uv pip install -e .

---

Configuration

Copy .env.example to .env and fill in the values (never commit .env):

PAPERCLIP_API_URL=http://localhost:3100   # "/api" is appended automatically
PAPERCLIP_API_KEY=pcp_board_...           # board key (recommended) or agent key
PAPERCLIP_COMPANY_ID=your_company_uuid    # from the UI URL /companies/{uuid}
PAPERCLIP_AGENT_ID=                       # optional: default agent for checkout_issue
PAPERCLIP_RUN_ID=                         # optional: real heartbeat run id, never invent one

PAPERCLIP_BASE_URL (0.1.x) is still accepted as an alias of PAPERCLIP_API_URL.

Credentials

Paperclip resolves a bearer token as a board API key first, then as an agent API key. What you can do depends on which one you configure:

Getting a board key

• CLI: paperclipai login mints one, or
• API: POST /api/board-api-keys from a logged-in board session, or
• On a local_trusted deployment: start this server with an empty PAPERCLIP_API_KEY (requests act as the local board operator) and call the create_board_api_key tool.

Run whoami in your MCP client to confirm which credential is active; the server also logs it at startup.

---

Usage

paperclip-mcp                          # streamable-http on http://127.0.0.1:9011/mcp
paperclip-mcp --port 9012
paperclip-mcp --transport stdio        # for Claude Desktop
paperclip-mcp --help

Claude Code

claude mcp add paperclip --transport http http://localhost:9011/mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "paperclip": {
      "command": "paperclip-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "PAPERCLIP_API_URL": "http://localhost:3100",
        "PAPERCLIP_API_KEY": "pcp_board_...",
        "PAPERCLIP_COMPANY_ID": "your_company_uuid"
      }
    }
  }
}

Auto-start with your MCP stack

curl -s --max-time 1 http://localhost:9011/mcp > /dev/null 2>&1 || \
  nohup paperclip-mcp > /tmp/paperclip-mcp.log 2>&1 &

---

Example interactions

"What needs my attention?"
→ get_attention_feed()   (board key)  /  get_sidebar_badges() + list_approvals()

"What is the Purchasing agent working on?"
→ list_issues(assignee_agent_id="...")

"Create a critical task for the CEO to find cheese suppliers in Barcelona, under PAP-12"
→ create_issue(title=..., priority="critical", assignee_agent_id="...", parent_issue_id="PAP-12")

"Mark PAP-42 done and leave a note"
→ update_issue(issue_id="PAP-42", status="done", comment="Verified in staging.")

"Approve the pending hire"
→ list_approvals() + approve(approval_id="...", decision_note="Go ahead")

"Which agent is burning the budget this week?"
→ get_cost_window_spend() + get_cost_breakdown(group_by="agent")

"Pause the Marketing agent and cancel its current run"
→ list_live_runs() + cancel_run(run_id="...") + pause_agent(agent_id="...")

"Run the weekly briefing routine now"
→ list_routines() + run_routine(routine_id="...")

---

Behaviour worth knowing

• Enums are validated client-side before any request: statuses backlog, todo, in_progress, in_review, done, blocked, cancelled; priorities critical, high, medium, low (there is no urgent).
• list_issues defaults to open statuses (everything except done/cancelled). Pass status="" for all.
• checkout_issue sends the required body {agentId, expectedStatuses}; the agent comes from the argument, then PAPERCLIP_AGENT_ID, then GET /agents/me.
• Errors are real MCP errors (isError: true) carrying the server's message, code, details and a hint, e.g. "Board access required → configure a board API key". A 409 means the state changed under you (conflict, paused project, stale revision): do not blindly retry.
• X-Paperclip-Run-Id is only sent when PAPERCLIP_RUN_ID is set, and only on writes. A fabricated run id violates a foreign key server-side.
• api_request lets you call any /api route that has no dedicated tool ({company} in the path expands to the configured company).

---

Development

pip install -e ".[dev]"
ruff check src/ tests/ && ruff format --check src/ tests/
mypy src/
pytest            # contract tests against a mocked Paperclip API

Layout: src/paperclip_mcp/core.py (config, HTTP client, errors, enums, FastMCP instance) and one module per domain under src/paperclip_mcp/tools/.

---

Architecture notes

• Who should use this MCP: human operators managing agents via Claude Code / Claude Desktop, with a board API key.
• Do agents need this MCP? No. Agents talk to the REST API directly during their heartbeat, and Paperclip ships @paperclipai/mcp-server for agent-side MCP access. If you switch to Hermes, either MCP works since Hermes supports MCP natively.
• Transport: streamable-http for Claude Code and mcp-proxy; stdio for Claude Desktop.
• Security: binds to 127.0.0.1 by default and carries your Paperclip key. Do not expose it publicly.

---

License

MIT — see LICENSE.