Cold Agent MCP

Stdio bridge for the hosted Cold Agent MCP server.

Cold Agent's canonical MCP endpoint is:

https://getcoldagent.com/api/mcp

Use this package when your MCP client prefers a local stdio command instead of a remote Streamable HTTP server.

Requirements

• Node.js 18 or newer
• A paid Cold Agent workspace
• A Cold Agent API key from Settings > API Keys

Install

Replace YOUR_COLD_AGENT_API_KEY with a key from Cold Agent Settings > API Keys.

One-line install:

claude mcp add -e COLD_AGENT_API_KEY=YOUR_COLD_AGENT_API_KEY cold-agent -- npx -y @razroo/cold-agent-mcp

Uninstall:

claude mcp remove cold-agent

Or manually add to .mcp.json (project-level) or ~/.claude/settings.json (global):

{
  "mcpServers": {
    "cold-agent": {
      "command": "npx",
      "args": ["-y", "@razroo/cold-agent-mcp"],
      "env": {
        "COLD_AGENT_API_KEY": "YOUR_COLD_AGENT_API_KEY"
      }
    }
  }
}

To uninstall manually, remove the cold-agent entry from the config file.

Add to your Claude Desktop MCP config:

{
  "mcpServers": {
    "cold-agent": {
      "command": "npx",
      "args": ["-y", "@razroo/cold-agent-mcp"],
      "env": {
        "COLD_AGENT_API_KEY": "YOUR_COLD_AGENT_API_KEY"
      }
    }
  }
}

To uninstall, remove the cold-agent entry from the config file.

One-line install:

codex mcp add cold-agent --env COLD_AGENT_API_KEY=YOUR_COLD_AGENT_API_KEY -- npx -y @razroo/cold-agent-mcp

Uninstall:

codex mcp remove cold-agent

Or manually add to ~/.codex/config.toml:

[mcp_servers.cold-agent]
command = "npx"
args = ["-y", "@razroo/cold-agent-mcp"]

[mcp_servers.cold-agent.env]
COLD_AGENT_API_KEY = "YOUR_COLD_AGENT_API_KEY"

To uninstall manually, remove the [mcp_servers.cold-agent] entry from the config file.

Add to opencode.json in your project root or ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cold-agent": {
      "type": "local",
      "command": ["npx", "-y", "@razroo/cold-agent-mcp"],
      "enabled": true,
      "environment": {
        "COLD_AGENT_API_KEY": "YOUR_COLD_AGENT_API_KEY"
      }
    }
  }
}

To uninstall, remove the cold-agent entry from mcp.

Open Settings -> MCP -> Add new MCP server, or add to ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "cold-agent": {
      "command": "npx",
      "args": ["-y", "@razroo/cold-agent-mcp"],
      "env": {
        "COLD_AGENT_API_KEY": "YOUR_COLD_AGENT_API_KEY"
      }
    }
  }
}

To uninstall, remove the entry from MCP settings.

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "cold-agent": {
      "command": "npx",
      "args": ["-y", "@razroo/cold-agent-mcp"],
      "env": {
        "COLD_AGENT_API_KEY": "YOUR_COLD_AGENT_API_KEY"
      }
    }
  }
}

To uninstall, remove the entry from the config file.

One-line install:

code --add-mcp '{"name":"cold-agent","command":"npx","args":["-y","@razroo/cold-agent-mcp"],"env":{"COLD_AGENT_API_KEY":"YOUR_COLD_AGENT_API_KEY"}}'

Or add to .vscode/mcp.json:

{
  "servers": {
    "cold-agent": {
      "command": "npx",
      "args": ["-y", "@razroo/cold-agent-mcp"],
      "env": {
        "COLD_AGENT_API_KEY": "YOUR_COLD_AGENT_API_KEY"
      }
    }
  }
}

To uninstall, remove the entry from MCP settings or delete the server from the MCP panel.

Any MCP client that supports stdio transport can use Cold Agent. The server config is:

{
  "command": "npx",
  "args": ["-y", "@razroo/cold-agent-mcp"],
  "env": {
    "COLD_AGENT_API_KEY": "YOUR_COLD_AGENT_API_KEY"
  }
}

To uninstall, remove the server entry from your client's MCP configuration.

Environment Variables

| Name | Required | Default | Description | | --- | --- | --- | --- | | COLD_AGENT_API_KEY | Yes | | Cold Agent API key. | | COLD_AGENT_MCP_URL | No | https://getcoldagent.com/api/mcp | Hosted MCP endpoint override. | | COLD_AGENT_MCP_TIMEOUT_MS | No | 60000 | Per-request timeout. | | COLD_AGENT_MCP_PROTOCOL_VERSION | No | 2025-11-25 | MCP protocol version header override. |

Remote MCP Config

If your client supports hosted Streamable HTTP servers with headers, you can skip this package:

{
  "mcpServers": {
    "cold-agent": {
      "url": "https://getcoldagent.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_COLD_AGENT_API_KEY"
      }
    }
  }
}

What This Package Does

This package is intentionally thin:

• reads JSON-RPC messages from stdio
• forwards them to https://getcoldagent.com/api/mcp
• attaches your Cold Agent API key as a bearer token
• writes MCP responses back to stdio

It does not contain Cold Agent business logic and does not store credentials.

Development

npm test

Publishing

The GitHub Actions publish workflow expects an NPM_TOKEN repository secret.

Dry-run from the GitHub CLI:

gh workflow run publish.yml --ref main -f dry_run=true -f tag=latest

Publish the version in package.json:

gh workflow run publish.yml --ref main -f dry_run=false -f tag=latest