OAuth, scopes and access tokens

Isolation MCP authentication is OAuth 2.1, in the shape the MCP specification defines. The client starts with only the URL https://mcp.isolation.cloud/mcp; a 401 points it at the authorization server; it registers itself, opens your browser, and on the consent screen you pick the organization it may work in and what it may do. It gets back an isomcp_ bearer that is you, in that organization, with the rights you approved. A host that cannot open a browser uses a personal access token instead: the same bearer, with no app behind it.

How does a client find the authorization server?

An unauthenticated POST to /mcp answers 401 with a WWW-Authenticate header that names the resource metadata:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Isolation", resource_metadata="https://mcp.isolation.cloud/.well-known/oauth-protected-resource"

That document names the authorization server, https://app.isolation.cloud, and the scopes it supports; its metadata at /.well-known/oauth-authorization-server lists the authorize, token, registration and revocation endpoints. Registration is dynamic and open: any client registers a name and redirect URIs and gets a client id, which grants nothing by itself. PKCE with S256 is mandatory, and the grant types are authorization code and refresh. Clients walk this on their own; see connect from Claude Code, Codex, Cursor.

What the consent screen asks

The browser lands on /authorize in Isolation, signed in as you, and sees three things. Who is asking: the app's name and address, and a reminder to approve only an app you started yourself. Where it would act: which organization, with your role in it; you pick one if you belong to several. What it could do: the rights it asked for, in plain sentences. Approve mints a single-use code, good for five minutes, that the client exchanges for tokens; Deny sends it back with access_denied and stores nothing.

The rights

A client that asks for nothing gets org:read, the read-only default. Every action carries one of these; tools/list shows only the tools the token covers, and a call outside them returns a refusal naming the missing right, so you can reconnect and approve it. org:admin on a Member's token gives nothing a Member cannot already do; the role check runs underneath. Roles are on organizations, roles and invites.

Tokens

Every token starts with isomcp_ and is stored hashed. An access token lasts one hour; the client refreshes it silently with a refresh token that lasts 90 days. Every call checks that the token is neither revoked nor expired and that you are still a member of that organization; leaving it, or being removed, ends the app's access on its next call.

A personal access token comes from the MCP page: under Connected apps, choose Connect with access token, name it, tick the rights, and pick an expiry (30 days, 90 days, a year, or never). The value is shown once. Hand it to the host as ISOLATION_TOKEN for npx isolation-mcp, or present it as a bearer from a terminal. The activity log shows its name as the channel, where an OAuth grant shows the app's.

Revoking

The same page lists everything you have connected, one row per app and organization, with its rights and dates. Revoke ends the whole grant at once: the refresh token and every access token it minted stop working immediately. Grants are yours: there is no organization-wide inventory, and an Owner who needs to end one removes the member, which ends all of theirs.

What a token can never do

More than you. A token is one member in one organization, so it cannot open, save, stop or read the logs of another member's session: sessions and workspaces are the member's; a teammate's is not found. An Admin's token lists and stops teammates' sessions, as on the website, and still cannot open them. It cannot act in a second organization; connect again for a second grant. It cannot reach view bytes: terminals, editors and file mounts travel from the browser through the doorman on their own view tokens, never the MCP.