paperclip-mcp

MCP server for the Paperclip AI agent orchestration platform.

Exposes Paperclip's REST API as Model Context Protocol tools, so any MCP-compatible AI assistant (Claude, etc.) can manage issues, agents, goals, approvals, and costs through natural language.

---

Features

Category	Tools
Issues	list_issues · get_issue · create_issue · update_issue · checkout_issue · release_issue · comment_on_issue · delete_issue
Agents	list_agents · get_agent · invoke_agent_heartbeat
Goals	list_goals · create_goal · update_goal
Approvals	list_approvals · approve · reject · request_approval_revision
Monitoring	get_cost_summary · get_dashboard · list_activity

---

Requirements

• Python 3.10+
• A running Paperclip instance
• Authentication — one of:
  • An Agent API key (Paperclip UI → Settings → API Keys), or
  • A browser session token (__Secure-better-auth.session_token cookie)

---

Installation

Option A — uvx (zero-install, recommended)

No install step needed. uvx fetches and runs the latest published release on demand:

uvx paperclip-mcp --transport stdio

Option B — pip / uv

pip install paperclip-mcp
# or
uv pip install paperclip-mcp

Option C — from source

git clone https://github.com/elevateinformatics/paperclip-mcp
cd paperclip-mcp
pip install -e .

---

Configuration

Environment variables

Variable	Required	Description
PAPERCLIP_COMPANY_ID	✅	Company UUID from the Paperclip URL
PAPERCLIP_API_KEY	⚠️ one-of	Bearer API key (Settings → API Keys → New Key)
PAPERCLIP_SESSION_TOKEN	⚠️ one-of	Value of __Secure-better-auth.session_token cookie
PAPERCLIP_BASE_URL	❌	Defaults to http://localhost:3100/api

Provide either PAPERCLIP_API_KEY (preferred for production) or PAPERCLIP_SESSION_TOKEN (useful when API keys are not available — uses your logged-in browser session).

How to get a session token

1. Log in to Paperclip in Chrome/Edge
2. DevTools → Application → Cookies → pick your Paperclip domain
3. Copy the value of __Secure-better-auth.session_token

Security: Session tokens grant full access to your user account. Treat them like passwords — never commit .env or share the value. They also expire and must be refreshed periodically.

.env file (local dev)

PAPERCLIP_BASE_URL=https://elevate-ai.up.railway.app/api
PAPERCLIP_COMPANY_ID=your_company_uuid
PAPERCLIP_API_KEY=your_api_key            # OR
PAPERCLIP_SESSION_TOKEN=your_session_cookie_value

---

Usage

Start the server

# HTTP (for Claude Code / mcp-proxy) — default port 9011
paperclip-mcp

# Custom port
paperclip-mcp --port 9012

# stdio transport (for Claude Desktop)
paperclip-mcp --transport stdio

# All options
paperclip-mcp --help

Register with Claude Code

# HTTP transport (persistent — survives Claude restarts)
claude mcp add paperclip --transport http http://localhost:9011/mcp

# stdio transport (Claude Desktop — add to claude_desktop_config.json)

Claude Desktop (claude_desktop_config.json)

Using uvx (no install required):

{
  "mcpServers": {
    "paperclip": {
      "command": "uvx",
      "args": ["paperclip-mcp@latest", "--transport", "stdio"],
      "env": {
        "PAPERCLIP_BASE_URL": "https://your-paperclip.example.com/api",
        "PAPERCLIP_COMPANY_ID": "your_company_uuid",
        "PAPERCLIP_API_KEY": "your_api_key"
      }
    }
  }
}

Or with a session token instead of an API key:

"env": {
  "PAPERCLIP_BASE_URL": "https://your-paperclip.example.com/api",
  "PAPERCLIP_COMPANY_ID": "your_company_uuid",
  "PAPERCLIP_SESSION_TOKEN": "your_session_cookie_value"
}

---

Example interactions

Once registered, you can ask your AI assistant:

"What tasks does the Purchasing agent have open?"
→ calls list_issues(assignee_agent_id="...", status="todo,in_progress")

"Create a task for the CEO agent to search for new cheese suppliers in Barcelona"
→ calls create_issue(title="Search cheese suppliers in Barcelona", assignee_agent_id="...")

"Approve the pending hire request"
→ calls list_approvals(status="pending") + approve(approval_id="...")

"How much have we spent on tokens this month, broken down by agent?"
→ calls get_cost_summary()

"Wake up the Administration agent now"
→ calls invoke_agent_heartbeat(agent_id="...")

---

Auto-start with the MCP stack

Add to your stack startup script:

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

---

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Lint
ruff check src/
ruff format src/

# Type check
mypy src/

# Tests
pytest

---

Architecture notes

• Who should use this MCP: Human operators managing agents via Claude Code or Claude Desktop.
• Do agents need this MCP?: No — Paperclip agents already interact with the REST API directly via HTTP in their HEARTBEAT protocol. This MCP is for the human operator layer.
• Hermes agents: If you switch to Hermes, this MCP is automatically available since Hermes supports MCP natively.
• Transport choice: Use streamable-http for Claude Code and mcp-proxy integrations. Use stdio for Claude Desktop.
• Security: The server binds to 127.0.0.1 by default (localhost only). Do not expose it publicly — it carries your Paperclip credentials.

---

License

MIT — see LICENSE.