Deploy and Host Paperclip MCP on Railway

Paperclip MCP is a Model Context Protocol server for the 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 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