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/:

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

Tool catalog

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.

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

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

Status & compatibility

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