Connect an MCP Client

Canopy publishes two MCP servers. Both speak the Model Context Protocol over Streamable HTTP, so any client that supports a remote MCP server can use them with a URL and no SDK.

The two servers

The documentation server

https://canopy-io.com/mcp

No authentication. It answers questions about the Developer Console and the Admin Workspace: where a task is done, what the exact controls are, why a button might be missing, and which API operation sits behind it. Every answer is read from the same tables the two applications build their own navigation from, so it uses the menu labels on screen and cannot name a page that no longer exists.

The account server

https://auth.canopy-io.com/mcp/v1

Authenticated with your own credential: an API key in X-API-Key, or a developer's bearer token. It exposes the public API as tools, one per operation and named by its operation id, and dispatches each call as you, so a tool can do exactly what your credential can do and nothing more. Start with the whoami tool, which reports the principal, Account, Application and Environment behind the connection.

Reading, not changing

The account server offers only the read operations unless the deployment enables write tools. On Canopy's hosted service they are off, so its tools read and never change anything.

Connect a client

Each client stores remote MCP servers in its own configuration; the URL is the same everywhere.

Claude Code

Run this once in a terminal, from the project you want it available in. It writes the server into ~/.claude.json, and sessions started afterwards can use it.

claude mcp add --transport http canopy-docs https://canopy-io.com/mcp

Add --scope user to make it available in every project. claude mcp list shows what is connected; claude mcp remove canopy-docs undoes it.

Claude Desktop and claude.ai

On a Free, Pro, or Max plan, go to Customize → Connectors (in the desktop app also reachable as Settings → Connectors), click Add custom connector, enter the URL https://canopy-io.com/mcp, and click Add. On a Team or Enterprise plan, an Owner adds it for the organization under Organization settings → Connectors with Add → Custom, and each member then connects from Customize → Connectors. Remote servers live here, not in claude_desktop_config.json: that file only holds servers that run on your own machine.

Cursor

Add the server to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project. A remote server needs only its URL; Cursor works out the transport.

{
  "mcpServers": {
    "canopy-docs": {
      "url": "https://canopy-io.com/mcp"
    }
  }
}

Other clients differ only in where the file lives. Anything that accepts a remote MCP server takes the URL directly.

The account server, with your key

The account server needs your credential, which every client sends as a request header. Create an API key in the Developer Console under Access Control → Integrations → API Keys, then attach it as X-API-Key. Treat whatever holds it as a secret: it is a live credential.

Claude Code takes the header on the command:

claude mcp add --transport http canopy https://auth.canopy-io.com/mcp/v1 \
  --header "X-API-Key: cnpy_your_key_here"

Cursor takes it in mcp.json:

{
  "mcpServers": {
    "canopy": {
      "url": "https://auth.canopy-io.com/mcp/v1",
      "headers": {
        "X-API-Key": "cnpy_your_key_here"
      }
    }
  }
}

In Claude Desktop or claude.ai, add a custom connector for https://auth.canopy-io.com/mcp/v1, choose No sign-in if the dialog asks how people connect, and add the key under Request headers as x-api-key. Request headers are a beta that only some organizations have; if the dialog shows no Request headers section, connect the account server from Claude Code or Cursor instead.

Check that it works

Start a new session in your client, since most read their configuration at startup, and ask something the model could not know from general knowledge:

Where do I rotate a webhook secret in Canopy? A working connection answers with the menu path in Canopy's own labels and the exact button, not a plausible-sounding guess.

Why can't I see the Create Role button? It should name the capability that gates it rather than suggesting you check your permissions generally.

Which endpoint evaluates a permission? It should return the operation id and a link to that endpoint's reference page.

Who am I? On the account server, whoami reports the credential behind the connection and what it can reach.

Or check it without a client

The documentation server answers a plain HTTP request, which is the quickest way to confirm reachability from a network:

curl -s -X POST https://canopy-io.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

What the documentation server answers

Five tools, all read-only:

find_surface: where a task is done, given what someone wants to do. Returns the pages that do it, ranked, each with its menu path, the capability that opens it, and its guide.

get_guide: a guide as markdown: the menu path, the controls to click in order, and the reasons a control may be missing.

explain_capability: what a capability such as env_roles.manage permits, and which pages it opens.

list_surfaces: every left-nav page of both applications. The same data as /ai/ui-map.json.

search_api: the API operation behind a task, with its operation id and reference page.

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.