--- title: "Deploy Paperclip MCP" description: "Deploy and Host Paperclip MCP with Railway" category: "Automation" url: https://railway.com/deploy/paperclip-mcp --- # Deploy Paperclip MCP Deploy and Host Paperclip MCP with Railway **[Deploy Paperclip MCP on Railway](https://railway.com/template/paperclip-mcp)** Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/paperclip-mcp/manifest.json - **Creator:** fournyp's Projects - **Category:** Automation ## Template content ### Paperclip MCP Gateway https://cdn.simpleicons.org/nginx - **Source:** FournyP/paperclip-mcp-railway-template - **Health check:** /health - **Public domain:** Yes ### Paperclip MCP https://api.iconify.design/simple-icons:modelcontextprotocol.svg - **Source:** FournyP/paperclip-mcp-railway-template ## Documentation ![Paperclip MCP logo](https://raw.githubusercontent.com/FournyP/paperclip-mcp-railway-template/main/icon.svg) # Deploy and Host Paperclip MCP on Railway Paperclip MCP is a Model Context Protocol server for the [Paperclip](https://github.com/paperclipai/paperclip) AI agent orchestration platform, built for the human operator: run your company of agents from Claude Code, Claude Desktop or any MCP client. It exposes the Paperclip REST API as 95 tools covering issues, agents, goals, projects, approvals, costs and budgets, routines, decisions, pipelines and the attention feed. This template deploys the MCP server behind an nginx bearer-token auth gateway, so an LLM can safely reach your Paperclip from a publicly reachable endpoint. ## About Hosting Paperclip MCP The MCP server has no client authentication of its own and binds to loopback upstream, because it is meant to sit next to your MCP client. This template places an nginx service in front that validates every request against a comma-separated list of bearer tokens before proxying to the MCP over Railway's private network. Keys can be issued and revoked one at a time without touching the MCP service. The MCP reaches Paperclip over `PAPERCLIP_API_URL`, which defaults to the private address of a service named `Paperclip` in the same project, so Paperclip itself never has to be public either. ## Common Use Cases - Ask "what needs my attention?" from Claude Code and get the attention feed, pending approvals and failed runs - Create, assign and close issues, leave comments and update documents without opening the Paperclip UI - Approve or reject agent hires and other board approvals from an MCP client - Pause, resume or terminate agents, cancel runs, set agent and company budgets - Inspect cost breakdowns by agent, project, provider or model, and run routines on demand ## Dependencies for Paperclip MCP Hosting The template ships the nginx auth gateway and the Paperclip MCP server. You bring the Paperclip: deploy the Paperclip template into the same project, or point the MCP at any external instance via `PAPERCLIP_API_URL`. ### Deployment Dependencies - A reachable Paperclip base URL, e.g. `http://paperclip.railway.internal:3100` for a Paperclip service in the same project. `/api` is appended automatically. - Paperclip must allow that hostname. Its private-hostname guard answers `403` to any `Host` outside its allowlist, so set `PAPERCLIP_ALLOWED_HOSTNAMES=paperclip.railway.internal` on the Paperclip service and redeploy it. - A board API key (`pcp_board_...`, full operator access) or an agent API key. Mint a board key with `paperclipai login` or `POST /api/board-api-keys` from a logged-in session. - The company UUID, visible in the Paperclip UI URL under `/companies/`. ## Implementation Details ### Architecture Components This template deploys two services: - **Gateway**: `nginx:alpine` with a public Railway domain. Validates `Authorization: Bearer KEY` against `API_KEYS` and proxies the rest to the MCP over Railway's private network with streaming-friendly settings. - **Paperclip MCP**: [wizarck/paperclip-mcp](https://github.com/wizarck/paperclip-mcp) built from source at a pinned commit (the `v0.2.0` tag) with its dependency tree frozen, running in streamable-HTTP transport mode. No public domain, reachable only via `paperclip-mcp.railway.internal:8000`. ### Authentication Clients must send `Authorization: Bearer KEY` where `KEY` is one of the comma-separated entries in `API_KEYS`. Generate keys with `openssl rand -hex 32`; rotating is a variable update plus a gateway redeploy, and the MCP service is untouched. The second boundary is the Paperclip credential itself. A board key can approve hires, pause and terminate agents, set budgets and mint API keys, so a leaked gateway key hands all of that over. An agent key limits the blast radius to what that one agent may do, at the cost of the board-only tools. For MCP clients that cannot send an `Authorization` header on their first request, set `PATH_KEY_AUTH=true` on the gateway to also accept the same key as a path segment at `/k/KEY/mcp`. It is off by default, since a key in a URL can be recorded by logs outside your control. ### Service Configuration - **MCP endpoint**: `https://GATEWAY_DOMAIN/mcp` (streamable-HTTP, `"type": "http"`). With Claude Code: `claude mcp add paperclip --transport http https://GATEWAY_DOMAIN/mcp --header "Authorization: Bearer KEY"`. - **Paperclip**: set `PAPERCLIP_API_URL`, `PAPERCLIP_API_KEY` and `PAPERCLIP_COMPANY_ID` on the MCP service. `PAPERCLIP_AGENT_ID` optionally names the default agent for `checkout_issue`; `PAPERCLIP_RUN_ID` is only ever a real heartbeat run id. - **Verify**: call the `whoami` tool. It reports whether the credential is a board or agent key; the MCP service also logs it at startup. ## License Information MIT (paperclip-mcp) + BSD-2-Clause (nginx). The template itself is MIT. ## Why Deploy Paperclip MCP on Railway? The auth gateway, private-network wiring and streamable-HTTP passthrough are all pre-configured, so giving an MCP client secure access to your Paperclip company is a one-click deploy next to the Paperclip service itself instead of a custom nginx and reverse-proxy project. ## Notes - Source repo: https://github.com/FournyP/paperclip-mcp-railway-template - Upstream MCP server: https://github.com/wizarck/paperclip-mcp - Paperclip: https://github.com/paperclipai/paperclip - Model Context Protocol: https://modelcontextprotocol.io ## Similar templates - [N8N Main + Worker](https://railway.com/deploy/n8n-main-worker) — Deploy and Host N8N with Inactive worker. - [Evolution API with n8n](https://railway.com/deploy/evolution-api-with-n8n) — Automate WhatsApp workflows with Evolution API, n8n, and Postgres. - [Postgres Backup](https://railway.com/deploy/postgres-s3-backups) — Cron-based PostgreSQL backup to bucket storage Open this page in a browser: https://railway.com/deploy/paperclip-mcp