Connect with OAuth Pro

OAuth (sign-in-with-Canopy) is the easiest, safest way to connect - no token to copy, rotate, or leak. You add the URL, approve once in your browser, and the client holds a short-lived, revocable, read-only grant. It's standard OAuth 2.1 with PKCE, so any client that supports remote MCP auth just works.

1Add the URL

Paste the server URL into your client - no token.

2Sign in

The client opens Canopy in your browser.

3Approve

Grant read-only access to your workspace.

4Connected

The agent queries your live maps.

Standards-compliant - Claude, Cursor & Codex all work

Canopy implements the full MCP authorization spec: OAuth 2.1 + PKCE (S256), Dynamic Client Registration (RFC 7591), discovery via protected-resource (RFC 9728) and authorization-server (RFC 8414) metadata, and resource indicators (RFC 8707) so tokens are audience-bound to this server. Any client that speaks remote-MCP OAuth connects with no extra setup - no client ID to register by hand.

Add the server

Point your client at the MCP URL with no token - it runs a one-time browser sign-in to get access. How you trigger that sign-in differs by client:

claude mcp add --transport http canopy https://canopy.8starlabs.com/api/mcp

# then, inside Claude Code, run /mcp → select "canopy" → Authenticate.
# A browser opens for sign-in; Claude Code stores the token for you.

Prefer a UI?

Most apps let you add the server without touching a config file - paste the URL, and the OAuth sign-in runs in your browser:

Claude Desktop / claude.ai - Settings → Connectors → Add custom connector → paste the URL.
Cursor - Settings → MCP → Add server → paste the URL.
Codex - no UI: add the url to ~/.codex/config.toml, then run codex mcp login canopy.

Approve access

Your client opens Canopy in the browser. Sign in (if you aren't already) and you'll see exactly what's being requested:

Authorize Claude

It wants read-only MCP access to the selected workspace.

This will allow it to

Read your maps - read-only, nothing else.

Deny Approve

what you'll see in the browser

Pick the workspace to connect from the dropdown (only Pro workspaces you belong to are listed), click Approve, and the client is connected.

What you're granting

Read-only · one workspace · revocable

An OAuth grant can only read your maps (services, spend, dependencies) - it can't create, edit, or delete anything, and it can't touch the REST write endpoints. It's scoped to the one workspace you approved, expires after 30 days, and can be revoked anytime.


Scope	`mcp:read` - read-only access to that workspace's maps
Workspace	the single workspace you approved
Plan	requires Pro (free workspaces are prompted to upgrade)
Who can approve	any member of the workspace
Lifetime	~30 days, then the client re-authorizes silently

Revoke access

Open Dashboard → Settings → Workspace → API → Connections, find the agent, and click Revoke - it's cut off immediately (the next tool call returns 401). Grants also expire after 30 days on their own, after which the client silently re-authorizes (you approve again). Removing the Canopy server from a client's config also stops it.

Settings → Workspace → API → Connections

Claude Code

Authorized today · expires in 30d

Revoke

Codex

Authorized today · expires in 30d

Revoke

one click cuts the agent off

Troubleshooting

Client doesn't open a browser / shows a token field. It may not support remote-MCP OAuth yet - use a workspace token instead.
"MCP requires a Pro workspace." OAuth (like all of MCP) is Pro - upgrade the workspace you're approving, or switch to a Pro workspace and reconnect.
It connected to the wrong workspace. The grant is bound to the workspace you picked from the dropdown at approval time. Remove and re-add the server, then choose the right workspace when you re-approve.

PreviousMCPMCP Next Connect with a tokenMCP

to paste into any AI.

Ask ChatGPT about this page.

Ask Claude about this page.

Need help?

Have ideas?

General inquiry? Email support.