MCP OAuth

OAuth 2.1 endpoints for MCP server authentication (RFC 9728, RFC 8414, RFC 7591)

Protected Resource Metadata (RFC 9728)

GET

http://localhost:3001

/.well-known/oauth-protected-resource/mcp

Bearer (JWT)

X-API-Key (header)

Returns metadata about the MCP protected resource, including the authorization server URL. AI clients use this to discover where to obtain access tokens.

Protected Resource Metadata (RFC 9728) › Responses

200

Protected Resource Metadata

RFC 9728 Protected Resource Metadata

ProtectedResourceMetadata

resource

string

URL of the protected resource (the MCP endpoint)

authorization_servers

string[]

bearer_methods_supported

string[]

resource_name

string

Authorization Server Metadata (RFC 8414)

GET

http://localhost:3001

/.well-known/oauth-authorization-server

Bearer (JWT)

X-API-Key (header)

Returns metadata about the OAuth 2.1 authorization server, including endpoints, supported grant types, and scopes. AI clients use this to discover the authorization and token endpoints.

Authorization Server Metadata (RFC 8414) › Responses

200

Authorization Server Metadata

RFC 8414 Authorization Server Metadata

AuthorizationServerMetadata

issuer

string

authorization_endpoint

string

token_endpoint

string

registration_endpoint

string

response_types_supported

string[]

grant_types_supported

string[]

code_challenge_methods_supported

string[]

scopes_supported

string[]

Dynamic Client Registration (RFC 7591)

POST

http://localhost:3001

/mcp/oauth/register

Bearer (JWT)

X-API-Key (header)

Registers a new OAuth client. AI clients call this endpoint to obtain a client_id and client_secret before initiating the authorization flow.

Dynamic Client Registration (RFC 7591) › Request Body

RFC 7591 Dynamic Client Registration request

DcrRequest

client_name

string · required

redirect_uris

string[] · required

grant_types

string[]

response_types

string[]

token_endpoint_auth_method

string

scope

string

Dynamic Client Registration (RFC 7591) › Responses

Client registered successfully

RFC 7591 Dynamic Client Registration response

DcrResponse

client_id

string

client_secret

string

client_id_issued_at

integer

client_name

string

redirect_uris

string[]

grant_types

string[]

response_types

string[]

token_endpoint_auth_method

string

scope

string

POST/mcp/oauth/register

fetch('http://localhost:3001/mcp/oauth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <token>'
  },
  body: JSON.stringify({
    client_name: 'Claude Desktop',
    redirect_uris: ['http://localhost:8080/callback'],
    grant_types: ['authorization_code'],
    response_types: ['code'],
    token_endpoint_auth_method: 'client_secret_post',
    scope: 'mcp:tools'
  })
})

Example Request Body

{
  "client_name": "Claude Desktop",
  "redirect_uris": [
    "http://localhost:8080/callback"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "client_secret_post",
  "scope": "mcp:tools"
}

json

application/json

Example Responses

{
  "client_id": "client_id",
  "client_secret": "client_secret",
  "client_id_issued_at": 0,
  "client_name": "client_name",
  "redirect_uris": [
    "string"
  ],
  "grant_types": [
    "string"
  ],
  "response_types": [
    "string"
  ],
  "token_endpoint_auth_method": "token_endpoint_auth_method",
  "scope": "scope"
}

json

application/json

Authorization Endpoint

GET

http://localhost:3001

/mcp/oauth/authorize

Bearer (JWT)

X-API-Key (header)

Initiates the OAuth 2.1 Authorization Code flow. Redirects the user to the Primebrick consent screen, then to Casdoor for authentication. On approval, redirects back with an authorization code. On denial, redirects back with error=access_denied.

Parameters:

response_type — must be code
client_id — from DCR registration
redirect_uri — must match a registered redirect URI
scope — requested scopes (e.g. mcp:tools)
state — client-generated state for CSRF protection
code_challenge / code_challenge_method — PKCE parameters (recommended)

Authorization Endpoint › query Parameters

response_type

string · enum · required

Enum values:

code

client_id

string · required

redirect_uri

string · uri · required

scope

string

state

string

code_challenge

string

code_challenge_method

string · enum

Enum values:

S256

Authorization Endpoint › Responses

Redirect to consent screen (or Casdoor if consent already approved). On success, redirects to redirect_uri with code and state. On denial, redirects with error=access_denied.

No data returned

Token Endpoint

POST

http://localhost:3001

/mcp/oauth/token

Bearer (JWT)

X-API-Key (header)

Exchanges an authorization code for an access token (and optional refresh token). The BE proxies the request to Casdoor's token endpoint using its own OIDC client credentials.

Content-Type: application/x-www-form-urlencoded

Token Endpoint › Request Body

OAuth 2.1 token exchange request (application/x-www-form-urlencoded)

TokenRequest

grant_type

string · enum · required

Enum values:

authorization_code

code

string · required

Authorization code from the authorize endpoint

redirect_uri

string · required

client_id

string · required

client_secret

string

code_verifier

string

PKCE code verifier

Token Endpoint › Responses

Token response

OAuth 2.1 token response

TokenResponse

access_token

string

token_type

string · enum

Enum values:

Bearer

expires_in

integer

refresh_token

string

scope

string

POST/mcp/oauth/token

fetch('http://localhost:3001/mcp/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    Authorization: 'Bearer <token>'
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: 'code',
    redirect_uri: 'redirect_uri',
    client_id: 'client_id',
    client_secret: 'client_secret',
    code_verifier: 'code_verifier'
  })
})

Example Request Body

grant_type=authorization_code&code=code&redirect_uri=redirect_uri&client_id=client_id&client_secret=client_secret&code_verifier=code_verifier

text

Example Responses

{
  "access_token": "access_token",
  "token_type": "Bearer",
  "expires_in": 0,
  "refresh_token": "refresh_token",
  "scope": "scope"
}

json

application/json

MCP

Protected Resource Metadata (RFC 9728)

GET

http://localhost:3001

/.well-known/oauth-protected-resource/mcp

Bearer (JWT)

X-API-Key (header)

Returns metadata about the MCP protected resource, including the authorization server URL. AI clients use this to discover where to obtain access tokens.

Protected Resource Metadata (RFC 9728) › Responses

200

Protected Resource Metadata

RFC 9728 Protected Resource Metadata

ProtectedResourceMetadata

resource

string

URL of the protected resource (the MCP endpoint)

authorization_servers

string[]

bearer_methods_supported

string[]

resource_name

string

Authorization Server Metadata (RFC 8414)

GET

http://localhost:3001

/.well-known/oauth-authorization-server

Bearer (JWT)

X-API-Key (header)

Returns metadata about the OAuth 2.1 authorization server, including endpoints, supported grant types, and scopes. AI clients use this to discover the authorization and token endpoints.

Authorization Server Metadata (RFC 8414) › Responses

200

Authorization Server Metadata

RFC 8414 Authorization Server Metadata

AuthorizationServerMetadata

issuer

string

authorization_endpoint

string

token_endpoint

string

registration_endpoint

string

response_types_supported

string[]

grant_types_supported

string[]

code_challenge_methods_supported

string[]

scopes_supported

string[]

Dynamic Client Registration (RFC 7591)

POST

http://localhost:3001

/mcp/oauth/register

Bearer (JWT)

X-API-Key (header)

Registers a new OAuth client. AI clients call this endpoint to obtain a client_id and client_secret before initiating the authorization flow.

Dynamic Client Registration (RFC 7591) › Request Body

RFC 7591 Dynamic Client Registration request

DcrRequest

client_name

string · required

redirect_uris

string[] · required

grant_types

string[]

response_types

string[]

token_endpoint_auth_method

string

scope

string

Dynamic Client Registration (RFC 7591) › Responses

Client registered successfully

RFC 7591 Dynamic Client Registration response

DcrResponse

client_id

string

client_secret

string

client_id_issued_at

integer

client_name

string

redirect_uris

string[]

grant_types

string[]

response_types

string[]

token_endpoint_auth_method

string

scope

string

Authorization Endpoint

GET

http://localhost:3001

/mcp/oauth/authorize

Bearer (JWT)

X-API-Key (header)

Parameters:

response_type — must be code
client_id — from DCR registration
redirect_uri — must match a registered redirect URI
scope — requested scopes (e.g. mcp:tools)
state — client-generated state for CSRF protection
code_challenge / code_challenge_method — PKCE parameters (recommended)

Authorization Endpoint › query Parameters

response_type

string · enum · required

Enum values:

code

client_id

string · required

redirect_uri

string · uri · required

scope

string

state

string

code_challenge

string

code_challenge_method

string · enum

Enum values:

S256

Authorization Endpoint › Responses

Redirect to consent screen (or Casdoor if consent already approved). On success, redirects to redirect_uri with code and state. On denial, redirects with error=access_denied.

No data returned

Token Endpoint

POST

http://localhost:3001

/mcp/oauth/token

Bearer (JWT)

X-API-Key (header)

Exchanges an authorization code for an access token (and optional refresh token). The BE proxies the request to Casdoor's token endpoint using its own OIDC client credentials.

Content-Type: application/x-www-form-urlencoded

Token Endpoint › Request Body

OAuth 2.1 token exchange request (application/x-www-form-urlencoded)

TokenRequest

grant_type

string · enum · required

Enum values:

authorization_code

code

string · required

Authorization code from the authorize endpoint

redirect_uri

string · required

client_id

string · required

client_secret

string

code_verifier

string

PKCE code verifier

Token Endpoint › Responses

Token response

OAuth 2.1 token response

TokenResponse

access_token

string

token_type

string · enum

Enum values:

Bearer

expires_in

integer

refresh_token

string

scope

string