Canopy

Connect Claude Agent SDK

Claude Agent SDK uses MCP for external tools. Canopy is hosted at https://mcp.trycanopy.ai/mcp (remote HTTP transport) and Claude needs explicit permission to call the tools via allowedTools.

Fast path: after Step 1, run npx @canopy-ai/sdk connect in your project root. It opens a consent page in your browser, then writes credentials to ~/.config/canopy/credentials and merges a canopy MCP server entry into any installed Claude Code, Cursor, Claude Desktop, Windsurf, Cline, VS Code, or Zed. Skip Steps 2 and 4 below.

Step 1 — Connect your agent in the dashboard

Canopy is bring-your-own-agent. This step doesn't create the agent itself — you've already built that, or are about to. It registers a Canopy-side record that pairs your agent with a spending policy and gives you an agt_… ID to use in your code.

Sign in at trycanopy.ai and go to Agents → Connect agent. Give the agent a name and pick (or create) a policy. The policy controls the spend cap, recipient allowlist, and approval threshold every payment from this agent will be evaluated against.

Step 2 — Copy your credentials

You need two values in your code:

  • Org API key (ak_live_… or ak_test_…) — from Settings → API Keys. Copy it the moment you create it; the plaintext is shown only once.
  • Agent ID (agt_…) — from the agent's detail page in /dashboard/agents.

Step 3 — Install the package

npm install @anthropic-ai/claude-agent-sdk

Step 4 — Set your environment variables

CANOPY_API_KEY=ak_live_xxxxxxxxxxxxxxxx
CANOPY_AGENT_ID=agt_xxxxxxxx

Use a .env file locally and your platform's secret manager in production. Never commit credentials.

Step 5 — Connect in your agent code

Paste the snippet below into your existing Claude Agent SDK agent.

// 1. Add to your .env:
// CANOPY_API_KEY=ak_live_xxxxxxxxxxxxxxxx

// 2. In your Claude Agent SDK app:
import { query } from '@anthropic-ai/claude-agent-sdk';

for await (const message of query({
  prompt: 'Find a data feed and pay for BTC orderbook depth.',
  options: {
    mcpServers: {
      canopy: {
        type: 'http',
        url: 'https://mcp.trycanopy.ai/mcp',
        headers: {
          Authorization: `Bearer ${process.env.CANOPY_API_KEY!}`,
          'X-Canopy-Agent-Id': 'agt_xxxxxxxx',
        },
      },
    },
    allowedTools: ['mcp__canopy__*'],
  },
})) {
  if (message.type === 'result') {
    console.log(message.result);
  }
}

Step 6 — Verify the connection

Run your agent once. As soon as Canopy receives a request from it, the dashboard flips the agent to connected and shows the first event captured. If nothing happens after a minute, see Troubleshooting.

Tool permissions

Claude MCP tools are named mcp__<server-name>__<tool-name>. With the server named canopy, Canopy tools appear as mcp__canopy__canopy_pay, mcp__canopy__canopy_discover_services, and so on.

Use allowedTools: ["mcp__canopy__*"] to allow the full Canopy tool set. To limit access, list individual tools instead:

allowedTools: [
  "mcp__canopy__canopy_pay",
  "mcp__canopy__canopy_get_budget",
]

Where to go next