Skip to main content
Glama
ai-zar

paperclip-mcp

by ai-zar
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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

Related MCP server: API to MCP

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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • API to MCP

    husw725
    F
    license
    Not graded
    quality
    D
    maintenance
    Converts any REST API endpoints into MCP tools, enabling AI clients like Cursor and Claude Desktop to call internal services directly.
    -

  • rest2mcp

    gonzalo123
    F
    license
    Not graded
    quality
    D
    maintenance
    Exposes any REST API as MCP tools, enabling AI agents to discover and call existing HTTP endpoints without modifying the original API.
    -

  • yellow-pages

    ethank64
    F
    license
    A
    quality
    D
    maintenance
    Exposes two MCP tools (discover and execute) that enable agents to query an OpenAPI schema via natural language and execute matched API operations.
    2
    -