Connect MCP hosts

Canopy ships a single Remote MCP endpoint at:

https://mcp.trycanopy.ai/mcp

That URL is everything. claude.ai, ChatGPT, Claude Desktop, Cursor, VS Code, Zed, Cline, Windsurf, and Claude Agent SDK all consume it directly. There's no package to install and no stdio process to manage.

How to add it

Web chat — claude.ai and ChatGPT

OAuth-based. Paste the URL into the host's Custom Connectors UI and complete the consent flow.

Host	Path
claude.ai (Pro / Max / Team / Enterprise)	Settings → Connectors → Add custom connector
ChatGPT (Plus / Pro / Team / Enterprise, Developer Mode on)	Settings → Apps & Connectors → Advanced settings → Developer mode → Connectors → Create

The consent screen lets you pick (or auto-create) which Canopy agent the connector spends as. Every payment that connector triggers is attributed to that agent in your dashboard.

Desktop / IDE hosts — Claude Desktop, Cursor, VS Code, Zed, Cline, Windsurf

These hosts speak HTTP MCP. Add this mcpServers block to the host's config (replace the placeholders with the API key and agent id from Dashboard → Agents → Connect agent):

{
  "mcpServers": {
    "canopy": {
      "type": "http",
      "url": "https://mcp.trycanopy.ai/mcp",
      "headers": {
        "Authorization": "Bearer ak_live_xxxxxxxxxxxxx",
        "X-Canopy-Agent-Id": "agt_xxxxxxxx"
      }
    }
  }
}

Per-host config locations

Host	Config file
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor (global)	`~/.cursor/mcp.json`
Cursor (workspace)	`<workspace>/.cursor/mcp.json`
VS Code	Workspace `.vscode/mcp.json` (with appropriate Copilot settings)
Zed	`~/.config/zed/mcp.json`
Cline / Windsurf	Settings → MCP Servers (UI), or the equivalent JSON file

After saving the config, restart the host. The Canopy tools (canopy_pay, canopy_check_url, canopy_discover_services, canopy_approve, canopy_deny, …) appear in the host's tool palette.

OpenClaw

OpenClaw needs two things: the skill (procedural context for the LLM — what canopy_* tools mean and the policy-gated outcome model) and a registered MCP server (the runtime wiring). The skill alone leaves the LLM with knowledge but no tools; the MCP alone gives tools without context. Both steps are manual; npx @canopy-ai/sdk connect does not auto-register OpenClaw (one OpenClaw install can host multiple Canopy skills bound to different agents, so one-shot binding doesn't fit).

# 1. Install the skill from ClawHub for the procedural context.
openclaw skills install canopy
 
# 2. Register the MCP server (replace placeholders with values from
#    Dashboard → Agents → Connect agent).
openclaw mcp set canopy '{"url":"https://mcp.trycanopy.ai/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer ak_live_xxxxxxxxxxxxx","X-Canopy-Agent-Id":"agt_xxxxxxxx"}}'

Restart OpenClaw. Verify with canopy_ping.

Why two steps? OpenClaw's skills install consumes ClawHub slugs, and ClawHub's manifest schema doesn't currently surface MCP-server registration fields. Until ClawHub adds first-class mcp block support, slug install gives only the procedural skill — registering the MCP itself is a separate openclaw mcp set step.

Hermes Agent

Hermes (Nous Research) follows the same two-thing model as OpenClaw — install the skill (procedural context) and register the MCP server (runtime tools). Both steps are manual: npx @canopy-ai/sdk connect does not auto-register Hermes (Hermes profiles can each map to a different Canopy agent, so one-shot binding doesn't fit).

# 1. Install the skill from skills.sh.
hermes skills install skills-sh/canopyio/skills

# 2. Add to ~/.config/hermes/config.yaml under mcp_servers
#    (replace placeholders with values from Dashboard → Agents → Connect agent).
mcp_servers:
  canopy:
    url: "https://mcp.trycanopy.ai/mcp"
    headers:
      Authorization: "Bearer ak_live_xxxxxxxxxxxxx"
      X-Canopy-Agent-Id: "agt_xxxxxxxx"

Run /reload-mcp in chat after saving.

The canonical skill source for either host lives at https://www.trycanopy.ai/skill.md. The ClawHub and skills.sh registries mirror it, but neither resolves an MCP-server registration from the manifest yet — that's a follow-up.

Programmatic — Claude Agent SDK

If you're building a TypeScript agent on top of @anthropic-ai/claude-agent-sdk, see the dedicated Claude Agent SDK guide. Same URL, configured inside query({ options: { mcpServers: ... } }).

What's available

The remote MCP exposes eleven tools — the full Canopy surface, identical to every other connection method:

canopy_pay, canopy_preview, canopy_fetch, canopy_check_url, canopy_get_approval_status, canopy_wait_for_approval, canopy_ping, canopy_get_budget, canopy_approve, canopy_deny, canopy_discover_services.

See the MCP tools reference for per-tool details.

Authentication

Web chat (claude.ai, ChatGPT): OAuth 2.1 with Dynamic Client Registration. Each connector binds to a specific agent at consent time.
Programmatic (Claude Desktop, Cursor, IDEs, Claude Agent SDK): Bearer-token auth using your existing org API key (ak_live_…) plus an X-Canopy-Agent-Id header. Same headers the SDK uses.

Either path produces the same observable behavior in your dashboard's activity feed.