Connect claude.ai and other OAuth clients
Add Browserberg as a remote MCP connector in claude.ai: the control plane is its own OAuth 2.1 server, the dashboard is the consent screen, and a grant is revocable.
Last updated:
What happens when you add the connector
Point a remote-MCP client at your API host’s /v1/mcp. The first request answers 401 with a WWW-Authenticate header naming the resource-metadata document; the client reads it, registers itself (dynamic client registration, public client with PKCE), and sends you to the authorization endpoint. That hands you to the dashboard: sign in if you are not, see which app is asking and where it will be sent back, and allow or deny. The client then exchanges its code for an access token and starts calling tools as you — every call carries your organisation, your role and your name in the audit log.
The endpoints
| Name | Type | Description |
|---|---|---|
/.well-known/oauth-authorization-server
|
GET | Discovery: endpoints, `code` response type, `S256` PKCE, `none` client authentication. |
/.well-known/oauth-protected-resource/v1/mcp
|
GET | Names `/v1/mcp` as the resource and this server as its authorization server. |
/oauth/register
|
POST | Dynamic client registration. Public clients only; redirect URIs must be `https` or loopback; rate-limited per address. |
/oauth/authorize
|
GET | Validates the client, redirect URI, PKCE challenge and optional `resource`, then redirects to the dashboard consent page. |
/oauth/token
|
POST | `authorization_code` (with the PKCE verifier) and `refresh_token` grants. Access tokens live one hour; refresh tokens rotate and live ninety days. |
/oauth/revoke
|
POST | Revokes an access or refresh token. Always answers 200. |
What the token is
An access token is a Browserberg API key of kind oauth, bound to you and to the client that asked. It is not restricted to the MCP endpoint — the hosted MCP server turns every tool call into an ordinary API request as the caller anyway — so it carries your role: a member’s token cannot create credentials, publish workflows, change pools, rotate secrets or seal the audit log. Connected apps are listed under Verbundene Apps on the API keys screen, and disconnecting one there revokes its tokens at once.
Read the discovery documents
BASE="https://browserberg.com"
# The discovery documents an MCP client reads on its own. No credential needed.
curl -s "$BASE/.well-known/oauth-authorization-server" \
| python3 -c 'import json,sys; d=json.load(sys.stdin); print("issuer:", d["issuer"]); print("authorize:", d["authorization_endpoint"].replace(d["issuer"], "")); print("token:", d["token_endpoint"].replace(d["issuer"], "")); print("pkce:", d["code_challenge_methods_supported"])'
curl -s "$BASE/.well-known/oauth-protected-resource/v1/mcp" \
| python3 -c 'import json,sys; d=json.load(sys.stdin); print("resource ends with:", d["resource"].rsplit("/", 2)[-2:])'
issuer: https://browserberg.com
authorize: /oauth/authorize
token: /oauth/token
pkce: ['S256']
resource ends with: ['v1', 'mcp']Note · Self-hosted
The OAuth server registers only when `BB_PUBLIC_BASE_URL` is set; the startup log says so otherwise. API keys keep working for every client that can set a header, OAuth or not.