Set up Paperclip MCP in VS Code

VS Code supports MCP servers through GitHub Copilot and other MCP-capable extensions. You can register Paperclip MCP at the workspace level — committing the config to source control so every contributor gets it automatically — or at the user level to share it across all projects on your machine. VS Code uses a slightly different config key format from Cursor, so make sure you follow the blocks below exactly for your target scope.

Config file location

Scope	Path
Workspace	`.vscode/mcp.json` in your project root (recommended for teams)
User (global)	User `settings.json` under the `mcp.servers` key

Commit .vscode/mcp.json to source control. All contributors automatically get the Paperclip MCP server without any per-machine setup.

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 — `.vscode/mcp.json`

Create or edit .vscode/mcp.json in your project root. Note that the VS Code workspace format uses a top-level servers key (not mcpServers) and requires a "type": "stdio" field.

npm (recommended)
Docker / Podman

Requires Node.js ≥ 22 on the host.

{
  "servers": {
    "paperclip": {
      "type": "stdio",
      "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.

{
  "servers": {
    "paperclip": {
      "type": "stdio",
      "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"
      ]
    }
  }
}

Configuration — user settings.json

To register the server globally for all projects, open User Settings JSON (Ctrl+Shift+P → Open User Settings (JSON)) and add the mcp.servers key. The "type": "stdio" field is still required.

npm (recommended)
Docker / Podman

{
  "mcp.servers": {
    "paperclip": {
      "type": "stdio",
      "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"
      }
    }
  }
}

{
  "mcp.servers": {
    "paperclip": {
      "type": "stdio",
      "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 the MCP server

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run MCP: Restart Server. Alternatively, restart VS Code entirely.

Open Copilot Chat and confirm tool count

Open a Copilot Chat panel and 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 VS Code

Config file location

Environment variables

Configuration — `.vscode/mcp.json`

Configuration — user settings.json

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 — .vscode/mcp.json

​Configuration — user settings.json

​Reload and verify

​See also

Build docs developers (and LLMs) love

Config file location

Environment variables

Configuration — `.vscode/mcp.json`

Configuration — user settings.json

Reload and verify

See also