paperclip-mcp

MCP (Model Context Protocol) server for the Paperclip AI agent orchestration API.

Exposes Paperclip's REST API as MCP tools so any MCP-compatible AI client (Claude Desktop, Cursor, Kiro, etc.) can manage your AI companies, agents, projects, and tasks.

Tools

Tool	Description
health_check	Check server health
list_companies	List all companies
get_company	Get a company by ID
create_company	Create a new company
list_agents	List agents for a company
get_agent	Get an agent by ID
list_projects	List projects for a company
get_project	Get a project by ID
create_project	Create a new project
list_issues	List issues for a company (optionally filtered by project)
get_issue	Get an issue by ID
create_issue	Create a new issue/task
list_goals	List goals for a company
create_goal	Create a new goal
get_costs	Get cost summary for a company
get_activity	Get recent activity for a company
list_approvals	List pending approvals for a company
approve	Approve a pending approval
reject_approval	Reject a pending approval
get_dashboard	Get dashboard summary for a company

Prerequisites

• Node.js >= 18
• A running Paperclip instance
• A Board API Key (required when Paperclip runs in authenticated mode)

Obtaining a Board API Key

Paperclip instances running in authenticated mode require a Board API Key for API access. To get one:

1. Open the Paperclip UI in your browser (e.g. http://localhost:3100)
2. Sign in with your account
3. Use the CLI auth flow — the Paperclip CLI (pnpm paperclipai) can generate a Board API Key via the challenge/approval process
4. Alternatively, use the API directly:

   # Create a CLI auth challenge
   curl -X POST http://localhost:3100/api/cli-auth/challenges \
     -H 'Content-Type: application/json' \
     -d '{"command": "paperclip-mcp", "clientName": "Paperclip MCP", "requestedAccess": "board"}'

   This returns an approvalUrl — open it in your browser while signed in to approve the challenge. The boardApiToken from the response is your API key.

Setup

Kiro CLI

Add to ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "paperclip": {
      "command": "node",
      "args": ["/path/to/paperclip-mcp/dist/index.js"],
      "env": {
        "PAPERCLIP_BASE_URL": "http://localhost:3100",
        "PAPERCLIP_API_KEY": "pcp_board_your-api-key-here"
      }
    }
  }
}

Then restart Kiro CLI to load the MCP server.

npx (no install required)

PAPERCLIP_BASE_URL=http://localhost:3100 PAPERCLIP_API_KEY=pcp_board_... npx paperclip-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "paperclip": {
      "command": "npx",
      "args": ["paperclip-mcp"],
      "env": {
        "PAPERCLIP_BASE_URL": "http://localhost:3100",
        "PAPERCLIP_API_KEY": "pcp_board_your-api-key-here"
      }
    }
  }
}

Cursor

Add to your MCP config (.cursor/mcp.json):

{
  "mcpServers": {
    "paperclip": {
      "command": "npx",
      "args": ["paperclip-mcp"],
      "env": {
        "PAPERCLIP_BASE_URL": "http://localhost:3100",
        "PAPERCLIP_API_KEY": "pcp_board_your-api-key-here"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
PAPERCLIP_BASE_URL	http://localhost:3100	Paperclip server URL
PAPERCLIP_API_KEY	(none)	Board API key (required for authenticated mode)

Development

git clone https://github.com/darljed/paperclip-mcp
cd paperclip-mcp
npm install
npm run build
PAPERCLIP_BASE_URL=http://localhost:3100 PAPERCLIP_API_KEY=pcp_board_... node dist/index.js

License

MIT