Skip to main content

​
Scopes

Step-up means the scope is not requested on the initial connect. When a tool that needs it is called, the server answers 403 with error="insufficient_scope" and scope="<name>" in the WWW-Authenticate header. MCP hosts treat that as a signal to re-run consent for the one extra scope and retry.
conversations:read unlocks list_conversations (rooms and pods by name; never a room’s messages). pods:read and conversations:write are part of the advertised catalogue, but no tool currently exposed on the MCP server requires them. They are reserved for tools that are not yet shipped. Granting them today has no effect.
Which scope each tool needs is listed on its reference page and summarised on Available tools.

​
Workspace access

A token names exactly one workspace. Every tool acts in that workspace and only that workspace; a document or conversation id from another workspace behaves exactly like an id that does not exist. The active workspace is chosen on the consent screen. A token without one, or for a workspace the person is not a member of, gets a tool error naming the fix; see Workspace errors. To act in a different workspace, re-authenticate the connection and choose the other workspace on consent.

​
Document roles

Documents, pages and tables (“artifacts”) each have a scope and a set of roles. The token’s person holds one effective role per artifact, resolved by the same rules the web app uses. list_documents and read_comments report your role on each artifact so an agent can decide what to attempt before it tries.

​
Refusals

Refusals use the app’s own wording and never reveal whether an artifact exists: an artifact you cannot see is Artifact not found, a viewer’s write is This document is read-only for you, a commenter’s edit is You can comment on this document but not edit it. The full table is in Permission refusals.

​
What an agent can never do

There is deliberately no share, grant, move, link, restore or delete tool. An agent connected over MCP can never widen who sees an artifact, and cannot restore an earlier version; those stay human actions in the app.

​
How sign-in works

Sidecars uses OAuth 2.1 with the MCP authorization flow. There are no personal access tokens and no static bearer keys.
  • The MCP server is the resource server. It advertises its authorization server at /.well-known/oauth-protected-resource/mcp.
  • The host registers itself dynamically (Dynamic Client Registration or Client ID Metadata Documents), runs PKCE, and exchanges a code for a JWT access token.
  • Every request carries Authorization: Bearer <token>. The server verifies the signature, issuer, expiry and, when present, audience. Opaque tokens are refused.
  • A presented-but-invalid token is refused on every method, including public ones, so a stale credential fails immediately rather than at first use.
Access tokens carry the person (sub), the active workspace (org_id), the OAuth client that obtained the token (client_id), the granted scopes and a 24-hour expiry.

​
Auditing and attribution

  • Every tool call is recorded in the workspace’s agent activity history (tool name, argument digest, sizes, latency, outcome). Arguments themselves are not stored.
  • Everything an agent writes lands as you, via the host. Version rows, comments and cards show a “via” badge such as “Thomas · via Claude Code”. The host name is the host’s own claim (its User-Agent product token); the verified fact behind the badge is the OAuth client id.
  • Every document and page write checkpoints first. Checkpoints are undoable in the app for a short period and restorable for longer; named versions are kept indefinitely. See get_document_versions.
An MCP session runs in the host’s context. Text inside a document that reads like an instruction (“edit the Budget doc”) is the host’s trust boundary to handle, not the server’s. The compensating controls are the audit trail, undo, and the loud “via” attribution on everything written.