Skip to main content
Connect an MCP-capable client to:
Use the API origin, not the web application origin. The MCP resource metadata is https://api.clearthedocket.com/.well-known/oauth-protected-resource/mcp. It identifies the authorization server and the resource that an MCP token must target.

​
Client setup

sh claude mcp add docket https://api.clearthedocket.com/mcp
The client registers or supplies a supported client identity, opens the person’s browser for consent, and uses PKCE S256. Docket grants only authorization_code and refresh_token flows. Read Authentication for the issuer, scope descriptions, and immediate revocation behavior.

​
Codex asks you to reconnect when several chats are open

Some Codex builds keep an older refresh token in each running chat. After another chat rotates that token, using the older token can revoke the Docket connection. Signing in again restores access but does not correct how those chats share refreshed credentials. Docket separates recognized public-client refreshes from the shared IP token-endpoint limit. Each authorization grant permits 120 refresh requests per fixed 60-second window across API instances, including recoverable retries. Separate grants have independent budgets. Unknown, expired and revoked credentials, confidential-client exchanges and authorization-code exchanges retain the ordinary IP limit. A grant-budget rejection returns HTTP 429, OAuth temporarily_unavailable and Retry-After; clients should wait and retry with their latest persisted refresh token. Throttling does not rotate or revoke credentials. For clients that can lose a rotated response before saving it, Docket supports a private device recovery key through the Docket-Refresh-Recovery header. Codex forwards configured http_headers to same-origin OAuth endpoints. Generate a separate random 32-byte base64url key per device, save it in that device’s private Codex configuration, and keep it stable across restarts. Never publish or log the key, share it between computers, or send it to a different issuer origin. The issuer binds the key’s digest to the encrypted rotation receipt when the rotation succeeds. After the ordinary 30-second replay grace, recovery requires both the predecessor refresh token and the matching device key. The original refresh deadline stays fixed; a consumed successor, revocation, changed authority, or expired original credential prevents recovery. If the recovered access token has expired or is nearly expired, Docket renews the active successor through ordinary token issuance and updates the receipt atomically. A failed local save can therefore be retried without another interactive authorization. A key added after a response was lost cannot recover an earlier unbound receipt. If your build lists mcp_oauth_refresh_coordination in codex features list, enable it:
Fully quit and reopen Codex so all existing connections use the new setting. A setting shown as enabled does not prove that an already-open connection adopted it. Apply the setting on each computer running Codex. If the connection still fails, authorize Docket once after the full restart. Do not repeatedly sign in while older connections keep using the previous refresh path. Restarting reuses the stored credentials. If the server rotated a refresh token but the client exited before saving its replacement, the old access token can still work until the next renewal. That renewal can fail even with coordination enabled. Docket recovers identical rotation retries for 30 seconds; a restart does not extend that window or repair a stale credential pair. This is an experimental Codex setting, verified with 0.162.0-alpha.17.2; check your installed build before using it. The upstream Codex report describes the stale-token failure and the coordination setting. Docket’s token lifetimes, permission checks, and replay protection remain unchanged. Coordination serializes refresh and credential persistence, but that build can still refresh separately for each chat receiving an expired-token response. Many simultaneous chats can therefore reach the token endpoint’s limit. HTTP 429 with temporarily_unavailable and Retry-After means to wait and retry; it does not mean the grant was revoked. Report repeated failures after a full restart so the client refresh path can be investigated. Increasing token lifetimes does not resolve this behavior.

​
Transport behavior

POST /mcp sends JSON-RPC messages. GET /mcp opens the notification stream. DELETE /mcp ends a server session when the client uses one. The server advertises tool and resource list-change notifications, resource subscriptions, prompts, completions, and logging. Resource notifications are best-effort. When Docket sends notifications/resources/updated, read the resource again instead of assuming replay or a complete event log.

​
Authority limit

MCP tools run under the consenting person’s current grants and the token’s scopes. A client cannot use work:write to write work the person cannot change. Docket invalidates authority immediately after revocation, scope reduction, client disablement, user removal, or live grant reduction.

MCP tools and resources

Read the registered tool names, resource URIs, prompts, and scope boundary.