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 integrates in two steps. The Canopy skill teaches the LLM what canopy_* tools mean and how the policy-gated outcome model works; the MCP-server registration is what actually wires the tools to the runtime. Both are required — skill alone leaves the LLM with knowledge but no tools, MCP alone gives tools without the procedural context.

Install the Canopy skill on ClawHub:

openclaw skills install canopy

Then 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 — it returns the resolved agent + org and a latency number.

Hermes Agent

Hermes (Nous Research) integrates the same two-step way. Install the Canopy skill from skills.sh (also reachable from any agentskills.io-compatible host):

hermes skills install skills-sh/canopyio/skills

Then add the MCP server to ~/.config/hermes/config.yaml:

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 Canopy tools become available immediately.

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 ten tools — the full Canopy surface, identical to every other connection method:

canopy_pay, canopy_preview, 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.