Skip to main content
Glama
elevateinformatics

paperclip-mcp

by elevateinformatics
OverviewSchemaRelated ServersScoreDiscussions
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

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 installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
3Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/elevateinformatics/paperclip-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server