MCP API Reference - PropelAuth Docs

MCP Authentication API Reference

These APIs facilitate user authorization through the MCP Client flow. For a guide on getting started with MCP, check out our MCP Documentation.

Authorize Endpoint

This redirects the user to the PropelAuth login page. This should be done in the browser.

The authorize endpoint is compatible with the code response type. Once the user has logged in successfully, it will redirect the user to the provided redirect_uri and include a code parameter in the URL.

Query Parameters

Name redirect_uri *Description
The URL where the user is directed to after a successful login. The provided URL must be set when creating the client in the MCP page.
Name client_id *Description
Found in the MCP page under OAuth Clients.
Name response_type *Description
Must be set to code.
Name state *Description
A randomly generated string used to guard against CSRF attacks. After the user successfully logs in, PropelAuth returns the state parameter so you can confirm it matches with the one you generated before the request.
Name code_challenge *Description
The URL-safe base64 encoded sha256 hash of a random string.
Name code_challenge_method *Description
Set to S256.
Name resource *Description
The resource server to request access to. This is the URL of your MCP server.
Name scope Description
Any scopes to request from the user. These must be set in the Scopes section of the MCP page.

{AUTH_URL}/oauth/2.1/authorize
    ?redirect_uri={REDIRECT_URI}
    &client_id={CLIENT_ID}
    &response_type=code
    &state={RANDOM_STRING}
    &code_challenge={CODE_CHALLENGE}
    &code_challenge_method=S256
    &scope={SCOPES} //read:user_data+tools:execute
    &resource={RESOURCE_SERVER_URL}

Token Endpoint

The token endpoint is used to generate an access token and refresh token. You can either exchange the code received from the Authorize Endpoint, or exchange an existing refresh token for a new access token and refresh token.

Request Headers

Name Content-Type *Type application/x-www-form-urlencoded

Request Body Parameters

Name client_id *Description
Found in the MCP page under OAuth Clients.
Name code *Description
The code received from the Authorize Endpoint.
Name redirect_uri *Description
The URL where the user is directed to after a successful login. The provided URL must be set when creating the client in the MCP page.
Name grant_type *Description
Must be set to authorization_code.
Name code_verifier *Description
The original secret created for the Authorize Endpoint.

curl --location --request POST '{AUTH_URL}/oauth/2.1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=0966..' \
--data-urlencode 'code=7KHj...' \
--data-urlencode 'redirect_uri=http://localhost:8000/callback' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code_verifier={CODE_VERIFIER}'

Successful Response

{
  "access_token": "28bdcd0d0d37761242...",
  "refresh_token": "c87981a37bd834c86...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "read:user_data"
}

Refresh Token Endpoint

Request Headers

Name Content-Type Type application/x-www-form-urlencoded Description

Request Body Parameters

Name client_id *Description
Found in the MCP page under OAuth Clients.
Name client_secret *Description
Found when creating a new OAuth Client in the MCP page.
Name refresh_token *Description
The refresh token to exchange.
Name grant_type *Description
Must be set to refresh_token.

Request

curl --location --request POST '{AUTH_URL}/oauth/2.1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=b2e7...' \
--data-urlencode 'client_id=0966...' \
--data-urlencode 'client_secret=0966...'

Successful Response

{
  "access_token": "80becb83aae...",
  "refresh_token": "ba58982483...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "read:user_data"
}

Introspection Endpoint

The introspection endpoint is used to validate an access token and retrieve a user's information and scopes from PropelAuth. Use the access token generated by the Token Endpoint in the request body.

Request Headers

Name Authorization Type Basic base64Encode(client_id:client_secret) Description
Basic Auth where the username is your Client ID and the password is your Client Secret. These are not the Client ID and Client Secret from your MCP Client. Get your Client ID and Client Secret for this API from the Request Validation section of the MCP page in the PropelAuth Dashboard.
Name Content-Type Type application/x-www-form-urlencoded Description

Request

curl --location --request POST '{AUTH_URL}/oauth/2.1/introspect' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic MDk2N...' \
--data-urlencode 'token=0966..'

Successful Response

{
  "active": true,
  "client_id": "016444257691d40192fb975819f937eb",
  "username": "user@acmeinc.com",
  "scope": "read:user_data",
  "sub": "667da91e-ae08-4056-93fb-24f6768e1205",
  "aud": "https://myserver.com/mcp",
  "iss": "{AUTH_URL}",
  "exp": 1768521751,
  "iat": 1768518151,

// If using org scopes
  "org_id": "{ORG_ID}",
  "users_org_roles": [
    "Admin"
  ],
  "users_org_permissions": [
    "can_view_resource",
    "can_edit_resource",
    ...
  ]
}

Registration Endpoint

Allows for Dynamic Client Registration with services that allow for it. Dynamic Client Registration must be enabled in order for this endpoint to be available.

Request Headers

Name Content-Type Type application/json Description

Request Body Parameters

Name redirect_uris *Description
An array of redirect URIs. The redirect URIs must be set as allowed in the Allowed MCP Clients section of the MCP page.
Name client_name Description
The name of the client.
Name client_uri Description
The URL of the client.
Name response_types Description
An array of response types. This must be set to code.
Name grant_types Description
An array of grant types. Supported types include authorization_code and refresh_token.
Name token_endpoint_auth_method Description
The supported token endpoint authentication method. Supported types include client_secret_basic, client_secret_post, and none.

Request

curl --location --request POST '{AUTH_URL}/oauth/2.1/register' \
--header 'Content-Type: application/json' \
--data '{
    "redirect_uris": ["http://localhost:3000/callback"],
    "client_name": "Example Client",
    "client_uri": "https://example.com",
    "response_types": ["code"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "client_secret_basic"
}'

Successful Response

{
  "client_id": "39f2400826394a2b3df76870236b5992",
  "client_secret": "39f2400826394a2b3df7...",
  "client_secret_expires_at": 0,
  "client_name": "Example Client",
  "client_uri": "https://example.com",
  "redirect_uris": [
    "http://localhost:3000/callback"
  ],
  "response_types": [
    "code"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "token_endpoint_auth_method": "client_secret_basic"
}

Authorization Server Discovery Endpoint

Returns a JSON listing of the OAuth endpoints, supported scopes and claims, and other details. Some MCP services can use this information to automatically construct requests to the PropelAuth MCP Client API.

Request

curl --location --request GET '{AUTH_URL}/.well-known/oauth-authorization-server/oauth/2.1'

Successful Response

{
  "authorization_endpoint":"{AUTH_URL}/oauth/2.1/authorize",
  "code_challenge_methods_supported":["S256"],
  "grant_types_supported":["authorization_code","refresh_token"],
  "introspection_endpoint":"{AUTH_URL}/oauth/2.1/introspect",
  "issuer":"{AUTH_URL}",
  "registration_endpoint":"{AUTH_URL}/oauth/2.1/register",
  "response_types_supported":["code"],
  "scopes_supported":["read:user_data","tools:execute","google_calendar:read"],
  "token_endpoint":"{AUTH_URL}/oauth/2.1/token",
  "token_endpoint_auth_methods_supported":["client_secret_basic","client_secret_post","none"]
}