OAuth Clients

Register OAuth client (anonymous DCR)

Changed on

Register a public OAuth client anonymously (RFC 7591 subset).

Returns 201 with the new client_id, or 200 with the existing row's client_id on an exact dedupe match (D8, extended per G13/#1251): (software_id + redirect-URI set), falling back to (client_name + redirect-URI set) for registrations without a software_id — so a pending client's awaiting-approval retry loop re-attaches instead of minting duplicate rows. Re-registering a client an administrator has deactivated re-enters the approval queue: the registration re-attaches (200) and the client awaits a fresh admin decision (#1312). No client_secret is ever issued here and no registration_access_token is returned (D12). New rows await admin approval unless the deployment auto-approves registrations (D9). The server.mcp.oauth.enabled gate lives on the route class — a disabled door 404s before this handler, its body validation, or the rate limiter ever run.

post/oauth-clients

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /oauth-clients
  • Auth: none required

Request body

application_typestring nullable

Accepted and echoed ('native' for desktop/CLI apps, per the 2026-07-28 MCP spec revision); localhost http redirect URIs are allowed regardless.

client_namestring required

Human-readable client name; self-asserted and not verified by the server.

grant_typesstring[] nullable

Subset of ['authorization_code', 'refresh_token'].

redirect_urisstring[] required

1-20 redirect URIs. https always; http for loopback hosts only; RFC 8252 §7.1 private-use (custom) schemes are accepted for native apps (browser-executable and other dangerous schemes are rejected).

response_typesstring[] nullable

Only ['code'] is supported.

scopestring nullable

Space-separated scopes requested as the client's ceiling (at most 100 tokens); capped to the scopes the server grants OAuth clients, and the full set when omitted.

software_idstring nullable

Stable identifier of the client software; with the redirect URIs it is used to match a repeat registration to the existing client.

software_versionstring nullable

Version of the client software.

token_endpoint_auth_methodstring nullable

Must be 'none' if supplied — this endpoint only registers public (secret-less, PKCE-only) clients.

Example request

{
  "application_type": "native",
  "client_name": "Cursor",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "redirect_uris": [
    "https://client.example.com/oauth/callback"
  ],
  "response_types": [
    "code"
  ],
  "scope": "apis:read capabilities:execute",
  "software_id": "com.example.mcp-client",
  "software_version": "1.4.2",
  "token_endpoint_auth_method": "none"
}

Response

Successful Response

application_typestring nullable

The application type as sent in the request; omitted if not sent.

client_idstring required

The client identifier to use in OAuth requests.

client_id_issued_atinteger required

Seconds since the Unix epoch at which the client_id was issued.

client_namestring required

The client name as sent in the request.

grant_typesstring[]

Grant types the client may use.

redirect_urisstring[] required

The registered redirect URIs.

response_typesstring[]

Response types the client may use; always code.

scopestring required

Space-separated scope ceiling granted to the client (the request's scope capped to the MCP tool-scope set).

software_idstring nullable

The software ID as sent in the request; omitted if not sent.

software_versionstring nullable

The software version as sent in the request; omitted if not sent.

token_endpoint_auth_methodstring

Always none: the client is public and uses PKCE.

Example response

{
  "application_type": "native",
  "client_id": "oc_Xk3vQ9mT2pLw8RzN5bYc1HdF7gJs4AeU",
  "client_id_issued_at": 1767225600,
  "client_name": "Cursor",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "redirect_uris": [
    "https://client.example.com/oauth/callback"
  ],
  "response_types": [
    "code"
  ],
  "scope": "apis:read capabilities:execute",
  "software_id": "com.example.mcp-client",
  "software_version": "1.4.2",
  "token_endpoint_auth_method": "none"
}

Changes