paperclip-mcp

MCP server that exposes the Paperclip control plane API as tools for Claude Code agents — manage issues, coordinate agents, post comments, and orchestrate work without direct API calls.

Quickstart

npx paperclip-mcp

Add to .claude/settings.json:

{
  "mcpServers": {
    "paperclip": {
      "command": "npx",
      "args": ["paperclip-mcp"],
      "env": {
        "PAPERCLIP_API_URL": "http://127.0.0.1:3100",
        "PAPERCLIP_API_KEY": "<your-api-key>",
        "PAPERCLIP_AGENT_ID": "<your-agent-id>",
        "PAPERCLIP_COMPANY_ID": "<your-company-id>"
      }
    }
  }
}

For heartbeat runs, Paperclip injects all required env vars automatically.

Installation

Three first-class variants:

npm

# one-shot (no install)
npx paperclip-mcp

# global install
npm install -g paperclip-mcp

Docker / Podman

# Docker
docker run --rm -i \
  -e PAPERCLIP_API_URL=http://host.docker.internal:3100 \
  -e PAPERCLIP_API_KEY=<your-api-key> \
  -e PAPERCLIP_AGENT_ID=<your-agent-id> \
  -e PAPERCLIP_COMPANY_ID=<your-company-id> \
  ghcr.io/bruhsb/paperclip-mcp:2.1.0

# Podman (same flags, replace docker → podman)
podman run --rm -i \
  -e PAPERCLIP_API_URL=http://host.containers.internal:3100 \
  -e PAPERCLIP_API_KEY=<your-api-key> \
  -e PAPERCLIP_AGENT_ID=<your-agent-id> \
  -e PAPERCLIP_COMPANY_ID=<your-company-id> \
  ghcr.io/bruhsb/paperclip-mcp:2.1.0

Compose stack (v2.1.0+)

Run the full Paperclip server + MCP server together via podman-compose (or docker-compose):

podman-compose up -d

See docs/guides/local-stack.md for the full compose setup, volume config, and health-check instructions.

Host integration

paperclip-mcp works with any MCP-compatible host. Platform-specific config files are in docs/installation/:

Host	Guide
Claude Code	docs/installation/claude-code.md
Claude Desktop	docs/installation/claude-desktop.md
Cursor	docs/installation/cursor.md
VS Code	docs/installation/vscode.md
Windsurf	docs/installation/windsurf.md

Each guide includes the exact config block, where to place it, and verification steps. Do not copy configs from this README — use the host-specific guides so you get the right file paths and format.

Environment variables

Variable	Required	Description
PAPERCLIP_API_KEY	Yes	Bearer token for API authentication
PAPERCLIP_API_URL	Yes	Base URL of the Paperclip API (e.g. http://127.0.0.1:3100)
PAPERCLIP_AGENT_ID	Yes	UUID of the agent running this MCP server
PAPERCLIP_COMPANY_ID	Yes	UUID of the company (used for company-scoped endpoints)
PAPERCLIP_RUN_ID	No	Heartbeat run ID — injected by Paperclip during agent runs
PAPERCLIP_TASK_ID	No	Task ID injected by Paperclip on @-mention wakes

Tool catalog

<!-- TOOLS-START -->

Domain	Tools
Identity	4
Issues	7
Comments	3
Documents	5
Agents & Organization	17
Dashboard	1
Approvals	11
Goals	4
Projects & Workspaces	8
Activity & Costs	5
Routines	9
Attachments	4
Labels	2
Companies	5
Plugins	6
Secrets	4
Run Observability	3
Feedback Traces	3
Company Import / Export	3
Total	104

<!-- TOOLS-END -->

Full per-tool reference: docs/tools/. Generated from Zod schemas — run npm run docs:generate to refresh.

Authentication

paperclip-mcp authenticates every request with a Bearer token derived from PAPERCLIP_API_KEY. The agent identity (PAPERCLIP_AGENT_ID) and company scope (PAPERCLIP_COMPANY_ID) are resolved at startup — the server will exit immediately if any required variable is missing. For details on generating API keys and scoping them to a specific agent, see docs/auth-keys.md.

Run ID injection

When PAPERCLIP_RUN_ID is set, the server automatically adds X-Paperclip-Run-Id: <runId> to all mutating requests (POST, PATCH, PUT, DELETE). This links every write action to the current heartbeat run for audit trail and traceability. No action is needed from the agent — injection is transparent.

Error handling

All tool handlers catch API errors and return isError: true results. The content[0].text field contains a human-readable message.

HTTP status	Behaviour
400	isError: true with validation message
401 / 403	isError: true with auth error
404	isError: true with not-found message
409	isError: true with conflict message (no retry)
5xx	isError: true with server error message

Architecture

Entry flow: src/index.ts creates an MCP Server, calls registerAllTools(server), then connects a StdioServerTransport for JSON-RPC over stdio.

Key modules:

• src/client.ts — PaperclipClient: typed HTTP wrapper (get, post, patch, put, delete). Injects Authorization header and X-Paperclip-Run-Id on mutations.
• src/auth.ts — Reads env vars at startup (fail-fast on missing required vars).
• src/errors.ts — PaperclipApiError for non-2xx HTTP responses.
• src/types.ts — Shared domain types.
• src/tools/index.ts — Tool registry. Collects ToolDefinition[] arrays from each tool module into ALL_TOOLS, builds a dispatch map, and registers MCP ListTools / CallTool handlers.
• src/tools/validation.ts — validate(zodSchema, args) helper and shared Zod schemas.

Documentation

• End-user — docs/README.md: quickstart, auth keys, troubleshooting, cookbook, host install guides, tool reference.
• Contributor — CONTRIBUTING.md: branch strategy, PR flow, dev environment, and conventions for adding new tools.
• Agent-orchestration — AGENTS.md: Paperclip-orchestrated agent protocol, BMAD integration, and heartbeat model.

Skills

paperclip-mcp ships public Claude Code skills under skills/ — paperclip-triage-inbox, paperclip-close-epic, paperclip-audit-approvals, paperclip-release-flow. Copy the relevant skill directory to ~/.claude/skills/ to use it in your Claude Code session. See skills/README.md for the full list and usage notes.

Development

Task	Command
Build	npm run build
Dev (live TS)	npm run dev
Start (compiled)	npm run start
Type-check only	npm run typecheck
Lint	npm run lint
Format	npm run format
Format check	npm run format:check
Run all tests	npm run test
Regenerate tool docs	npm run docs:generate
Check doc links	npm run docs:check

Branch strategy: feature/* → main (squash-merge via PR)

Status & compatibility

Component	Version
MCP protocol (@modelcontextprotocol/sdk)	1.29.0
Node.js (minimum)	22
Paperclip API	v2

Releases

Releases are automated. Squash-merge a PR to main; semantic-release handles version bumping, changelog generation, npm publish, and GitHub release creation. No manual publish step is needed.

To trigger a release, open a PR from your feature branch to main. Once merged, the release.yml workflow runs npx semantic-release automatically. The version bump is determined by the commit types since the last release:

• fix: commits → patch release
• feat: commits → minor release
• BREAKING CHANGE: commits → major release
• chore:, docs:, test: commits → no release

Contributing

See CONTRIBUTING.md for the full contributor guide, including how to add new tools, branch naming, commit format, and PR process.

Security

Please report security vulnerabilities via the process described in SECURITY.md. Do not open public issues for security bugs.

Links

• Paperclip — the control plane this MCP server wraps
• Model Context Protocol — the open protocol standard
• npm package
• GitHub

License

MIT