mcp-paperclip

An MCP (Model Context Protocol) server that gives AI agents programmatic access to the Paperclip agent platform API. Agents can list their issues, post comments, update statuses, search across the backlog, and wake other agents -- all through structured MCP tool calls instead of hand-constructing curl commands.

Features

• Issue management -- list, get, update, and search issues assigned to the agent
• Comments -- list and create comments on issues
• Agent lifecycle -- get current agent identity, wake other agents for cross-agent delegation
• Run visibility -- list and inspect heartbeat runs
• Works with Claude Code, Gemini CLI, and any MCP-compatible client
• Model-agnostic: eliminates API param-name mismatches across different LLM backends

Quick Start

1. Install

npm install @devli13/mcp-paperclip

Or clone locally:

git clone https://github.com/devli13/mcp-paperclip.git
cd mcp-paperclip
npm install

2. Configure

Add to your .mcp.json (Claude Code) or .gemini/settings.json (Gemini CLI):

{
  "mcpServers": {
    "paperclip": {
      "command": "npx",
      "args": ["-y", "@devli13/mcp-paperclip"]
    }
  }
}

The server reads its configuration from environment variables that Paperclip's adapter automatically injects when spawning agent sessions. No manual env setup is needed for standard Paperclip deployments.

For standalone testing:

PAPERCLIP_API_URL=http://127.0.0.1:3100 \
PAPERCLIP_API_KEY=your_key \
PAPERCLIP_COMPANY_ID=your_company_uuid \
PAPERCLIP_AGENT_ID=your_agent_uuid \
node server.js

Configuration

Environment Variable	Required	Description	Default
PAPERCLIP_API_URL	No	Paperclip API base URL	http://127.0.0.1:3100
PAPERCLIP_API_KEY	Yes*	Agent API key (auto-injected by Paperclip adapter)	--
PAPERCLIP_COMPANY_ID	Yes	Company UUID (auto-injected by adapter)	--
PAPERCLIP_AGENT_ID	Yes**	Current agent UUID (auto-injected by adapter)	--

* In local_trusted mode (loopback only), the API key may be optional.
** Required for list_my_issues and list_my_runs. Other tools work without it.

Tools

Tool	Description	Key Parameters
list_my_issues	List issues assigned to the current agent	status, limit
get_issue	Get issue details, optionally with comments	issueId, includeComments
list_issue_comments	List comments on an issue	issueId, limit
create_comment	Post a comment on an issue	issueId, body
update_issue	Update status, priority, title, assignee	issueId, status, priority, ...
search_issues	Search issues by title/description substring	query, limit
list_my_runs	List recent heartbeat runs for current agent	limit
get_run	Get details of a specific run	runId
get_agent_me	Get current agent identity/profile	--
wakeup_agent	Wake another agent to handle a task	agentId, reason

Example: list open issues

{
  "name": "list_my_issues",
  "arguments": {
    "status": "in_progress",
    "limit": 10
  }
}

Example: cross-agent delegation

{
  "name": "wakeup_agent",
  "arguments": {
    "agentId": "target-agent-uuid",
    "reason": "Please review and merge PR #42"
  }
}

Limitations

• search_issues performs client-side substring matching over a single page of results. It is not full-text search.
• The server assumes Paperclip's current REST API shape. If Paperclip changes endpoint names or response formats, this server may need updating.
• wakeup_agent triggers an on-demand heartbeat run. The target agent must have wakeOnDemand enabled in its config.

Contributing

Issues and pull requests are welcome! Please open an issue first to discuss significant changes.

License

MIT