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 every operation of the public API as a tool 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 is read-only 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

Settings → Developer → Edit Config, add the server, and restart the app.

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

Cursor

Settings → MCP → Add new global MCP server, using the same JSON as above.

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 clients pass as a header. Create an API key in the Developer Console under Access Control → Integrations → API Keys, then point the client at the API origin with the key attached. Treat that configuration file as a secret: it now holds a live credential.

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

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 routed 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.