Set up Paperclip MCP in Windsurf

Windsurf (Codeium’s AI IDE) supports MCP servers through a JSON config file with the same mcpServers shape used by Cursor. Once the paperclip entry is in place and the servers are reloaded, all 104 Paperclip tools become available in Windsurf’s Cascade chat panel — letting you manage issues, coordinate agents, handle approvals, and more without leaving your editor.

Config file location

Windsurf’s MCP config file location has changed between releases. Refer to the Windsurf official MCP documentation for the current path on your installed version. The JSON shape shown below is stable: an mcpServers object with command, args, and env keys.

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 automatically by Paperclip during agent runs
`PAPERCLIP_REQUEST_TIMEOUT_MS`	No	HTTP request timeout in milliseconds (default: `30000`)

Configuration

Open (or create) Windsurf’s MCP config file and paste the block for your preferred variant.

npm (recommended)
Docker / Podman

Requires Node.js ≥ 22 on the host. No container runtime needed.

{
  "mcpServers": {
    "paperclip": {
      "command": "npx",
      "args": ["-y", "paperclip-mcp"],
      "env": {
        "PAPERCLIP_API_KEY": "YOUR_API_KEY",
        "PAPERCLIP_API_URL": "YOUR_API_URL",
        "PAPERCLIP_AGENT_ID": "YOUR_AGENT_ID",
        "PAPERCLIP_COMPANY_ID": "YOUR_COMPANY_ID"
      }
    }
  }
}

Isolated runtime — no Node.js required on the host. Replace podman with docker in command if you are using Docker.

{
  "mcpServers": {
    "paperclip": {
      "command": "podman",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PAPERCLIP_API_KEY=YOUR_API_KEY",
        "-e",
        "PAPERCLIP_API_URL=YOUR_API_URL",
        "-e",
        "PAPERCLIP_AGENT_ID=YOUR_AGENT_ID",
        "-e",
        "PAPERCLIP_COMPANY_ID=YOUR_COMPANY_ID",
        "ghcr.io/bruhsb/paperclip-mcp:2.1.0"
      ]
    }
  }
}

Reload and verify

Reload MCP servers in Windsurf

Open the Command Palette and run Windsurf: Reload MCP Servers. Alternatively, restart Windsurf entirely.

Open Cascade chat and confirm tool count

Ask: “What paperclip tools do you have?”You should see 104 tools listed. If the count is lower or the server does not appear, check the troubleshooting guide.

For Paperclip-orchestrated heartbeat runs, PAPERCLIP_RUN_ID is injected automatically into the process environment — you do not need to add it to the config file.

Get Started

Installation

Guides

Architecture

Reference

Set up Paperclip MCP in Windsurf

Config file location

Environment variables

Configuration

Reload and verify

See also

Build docs developers (and LLMs) love

Get Started

Installation

Guides

Architecture

Reference

Documentation Index

​Config file location

​Environment variables

​Configuration

​Reload and verify

​See also

Build docs developers (and LLMs) love

Config file location

Environment variables

Configuration

Reload and verify

See also