Claude Cowork

Claude Cowork connects to custom MCP servers via OAuth 2.1. Amble exposes the standard OAuth metadata at `/.well-known/oauth-authorization-server` and supports Dynamic Client Registration (RFC 7591), so Cowork can auto-register and complete the handshake without manual config.

## Connect Cowork to Amble

1. In Cowork, open **Settings → Connectors → Add custom connector**.
2. Set the **MCP server URL** to `https://app.sprinter.ai/api/mcp/server`.
3. Leave **Advanced settings → OAuth client ID / secret** blank — Cowork will auto-register via DCR.
4. Click **Connect**.
5. You'll be redirected to Amble. If you're not signed in, you'll see Amble's normal login page first — any Supabase Auth provider you have enabled (Google, email/password, magic link, …) works here. There's no separate "OAuth login" — it's the same `/auth/login` route used everywhere else in the app.
6. On the consent screen, **pick the tenant** the connector should access and click **Approve**.
7. Cowork lands back on its own page with the connection live.

The connector now sees only the tenant you picked, with the scopes you approved. Switching tenants requires disconnecting + re-adding (per-token tenant lock is by design).

## Scopes

Cowork requests these scopes by default. You can revoke any subset on the consent screen — the resulting token only carries what you approve.

| Scope | What it grants |
|---|---|
| `tools:execute` | Run AI tools registered for the tenant |
| `skills:read` | List + read skill definitions |
| `views:read` | List + read saved views |
| `offline_access` | Issue a refresh token so Cowork can stay connected |

Additional scopes (`entities:read`, `entities:write`, `documents:read/write`, `chat:create`, …) are available and map 1:1 to the same vocabulary as API keys. Add them in the Cowork request payload if your workflow needs more access; the consent screen will display them.

## Permission inheritance

The access token issued to Cowork carries a snapshot of the **intersection** of:

- The permissions granted by the OAuth scopes you approved
- Your actual tenant permissions (i.e., what your role allows in that tenant)

This means a tenant member who only has `viewer` permissions gets a token that can read but not write, even if `entities:write` was requested. The snapshot is refreshed every time the token rotates (every 1 hour via refresh-token rotation).

## Disconnecting

In Cowork, click **Disconnect** on the connector card. Cowork calls Amble's `/oauth/revoke` endpoint (RFC 7009) to invalidate the access token + refresh token. You can also revoke from Amble's Admin → API Keys panel if you've lost access to Cowork.

## Programmatic API keys

If you're building a server-to-server integration (CI script, agent runner, n8n flow), keep using API keys (`sk_…`) instead — see [API access](/docs/features/api-keys). OAuth is for browser-based MCP hosts that can complete a user-consent flow. Both work side-by-side on the same MCP endpoint.

## Reference

- Spec: ADR-0026 (OAuth 2.1 authorization server for MCP)
- Discovery: `GET /.well-known/oauth-authorization-server`, `GET /.well-known/oauth-protected-resource`
- RFC pins: 8414 (auth server metadata), 9728 (protected resource metadata), 7591 (DCR), 6749 + 7636 (OAuth 2.1 + PKCE), 7009 (revocation)
- MCP authorization spec: https://modelcontextprotocol.io/specification/draft/basic/authorization (2025-11-25)