# 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](https://docs.propelauth.com/mcp-authentication/overview).

---

## [Authorize Endpoint](https://docs.propelauth.com/reference/api/mcp#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](https://docs.propelauth.com/reference/api/mcp#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](https://docs.propelauth.com/reference/api/mcp#authorize-endpoint), or [exchange an existing refresh token](https://docs.propelauth.com/reference/api/mcp#refresh-token-endpoint) 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](https://docs.propelauth.com/reference/api/mcp#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](https://docs.propelauth.com/reference/api/mcp#authorize-endpoint).

```bash
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

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

---

## [Refresh Token Endpoint](https://docs.propelauth.com/reference/api/mcp#refresh-token-endpoint)
The token endpoint is used to generate an access token and refresh token. You can either [exchange the code](https://docs.propelauth.com/reference/api/mcp#token-endpoint) received from the [Authorize Endpoint](https://docs.propelauth.com/reference/api/mcp#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 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

```bash
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

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

---

## [Introspection Endpoint](https://docs.propelauth.com/reference/api/mcp#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](https://docs.propelauth.com/reference/api/mcp#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

```bash
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

```json
{
  "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](https://docs.propelauth.com/reference/api/mcp#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

```bash
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

```bash
{
  "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](https://docs.propelauth.com/reference/api/mcp#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

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

### Successful Response

```bash
{
  "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"]
}
```