Authentication

The deskbird MCP server uses OAuth 2.1 with the authorization code flow and PKCE. Users authenticate with their own deskbird account, and every connection requires explicit consent on a deskbird-hosted screen. API keys are not accepted on the MCP endpoint.

Most users never see any of this: connecting from Claude handles the whole flow automatically. This page is a reference for what happens underneath.

Flow summary

The MCP client calls POST /mcp without a token and receives 401 Unauthorized with a WWW-Authenticate header pointing to the resource metadata.

The client discovers the authorization server through the well-known documents below.

The client starts an authorization code flow with PKCE (S256). The user logs in to deskbird and approves the consent screen.

The client exchanges the code for tokens at the token endpoint and calls POST /mcp with the access token as a Bearer header.

Discovery

Document	URL
Protected resource metadata (RFC 9728)	`https://connect.deskbird.com/.well-known/oauth-protected-resource`
Authorization server metadata (RFC 8414)	`https://connect.deskbird.com/.well-known/oauth-authorization-server`

Client registration

The server does not offer dynamic client registration (DCR). Every client must identify itself with a Client ID Metadata Document (CIMD): the client_id is an HTTPS URL pointing to a JSON document that describes the client, which deskbird fetches and validates. CIMD support is the requirement to connect – a client that cannot present a CIMD is not able to authenticate, regardless of anything else.

Redirect URIs are restricted to an allowlist:

the hosted Claude callback https://claude.ai/api/mcp/auth_callback, and

standards-compliant localhost loopback redirects (RFC 8252), used by native desktop clients.

Supported clients

Claude (web, desktop, mobile, and Claude Code) – supported.

Other native clients that support CIMD – supported. For example, the ChatGPT Codex desktop app uses a loopback redirect and presents a CIMD, so it connects.

Clients without CIMD support – not supported yet. For example, Codex on the web does not present a CIMD, so it cannot connect even though it is otherwise a valid OAuth client.

If you are building an MCP client and want to integrate with deskbird, contact us. The main requirement is CIMD support.

Scope and tokens


Scope	`mcp` (the only scope)
Access token	Signed JWT, valid for 1 hour
Refresh token	Opaque, single use, rotated on every refresh
Session lifetime	30 days per refresh token, 90 days absolute per connection

Refresh tokens rotate: each refresh invalidates the old token and returns a new one. Reusing an already-rotated refresh token is treated as theft and revokes the whole session chain. After the 90-day absolute lifetime, the user reconnects and consents again.

Every refresh also re-checks that the user is still active, still an admin, and still in the same company.

Requirements re-checked on every request

A valid token alone is not enough. On each POST /mcp call the server verifies:

the token signature, audience, issuer, and expiry

the mcp scope and the admin role

that the company still has the MCP server feature

If any check fails, the request returns 401 (invalid token) or 403 (feature or role no longer available).

Disconnecting

Removing the connector in Claude stops its access. Tokens also expire on their own as described above.

Flow summary#

Discovery#

Client registration#

Supported clients#

Scope and tokens#

Requirements re-checked on every request#