CIMD Registration Flow

This page assumes familiarity with the MCP Auth overview. Actor terms (MCP Client, MCP Server, Authorization Server, User Agent) are defined there.

When to Use CIMD

MCP client is a public client (no client secret)
Client can host a publicly reachable metadata document URL
Client controls its own metadata lifecycle (update without re-registering)
Open/open-source MCP clients distributed to many users
If your client is confidential or cannot host a public URL, see DCR instead

Sequence Diagram

How It Works

Each step corresponds to an arrow in the sequence diagram above.

Step 1: MCP Client sends an initial MCP request to MCP Server without an access token.
Step 2: MCP Server returns HTTP 401 Unauthorized with a WWW-Authenticate header containing the resource_metadata URL.
Step 3: MCP Client requests Protected Resource Metadata from MCP Server:
```
GET https://mcp.example.com/.well-known/oauth-protected-resource
```

Step 4: MCP Server returns resource metadata including the Authorization Server issuer URI:

{
  "resource": "https://mcp.example.com/mcp",
  "authorization_servers": ["https://tenant.hub.loginradius.com/service/oidc/{app}"]
}

Step 5: MCP Client fetches Authorization Server metadata using the issuer URI from step 4:

GET https://tenant.hub.loginradius.com/service/oidc/{app}/.well-known/oauth-authorization-server

GET https://tenant.hub.loginradius.com/.well-known/oauth-authorization-server/service/oidc/{app}

Step 6: Authorization Server returns metadata confirming supported endpoints and CIMD support:

{
  "issuer": "https://tenant.hub.loginradius.com/service/oidc/{app}",
  "authorization_endpoint": "https://tenant.hub.loginradius.com/service/oidc/{app}/authorize",
  "token_endpoint": "https://tenant.hub.loginradius.com/service/oidc/{app}/token",
  "registration_endpoint": "https://tenant.hub.loginradius.com/service/oidc/{app}/register",
  "client_id_metadata_document_supported": true
}

Step 7: MCP Client uses a hosted Client ID Metadata Document (CIMD) URL as client_id and constructs the authorization URL.

The client:
- Sets client_id to the CIMD URL (e.g., https://client.example.com/.well-known/oauth/client-metadata.json)
- Generates PKCE parameters (code_challenge, code_verifier) using S256
- Includes the OAuth resource parameter
- Opens the authorization URL in the browser:
```
GET https://tenant.hub.loginradius.com/service/oidc/{app}/authorize
  ?response_type=code
  &client_id=https://client.example.com/.well-known/oauth/client-metadata.json
  &redirect_uri=https://client.example.com/callback
  &scope=openid
  &code_challenge={s256_code_challenge}
  &code_challenge_method=S256
  &resource=https://mcp.example.com/mcp
```
Step 8: User Agent sends the authorization request to Authorization Server; user authenticates and consents. Authorization Server validates the CIMD metadata document:
- client_id must match the hosted metadata URL
- redirect_uris must match the metadata document
- Server may enforce SSRF protections and domain trust policies
Authorization Server redirects User Agent to redirect_uri with authorization code and iss:
```
GET https://client.example.com/callback?code={authorization_code}&iss=https://tenant.hub.loginradius.com/service/oidc/{app}
```
Step 9: User Agent delivers the authorization callback to MCP Client, which verifies that iss matches the expected Authorization Server issuer (mix-up attack protection).

Step 10: MCP Client exchanges code + code_verifier + resource at the token endpoint:

POST https://tenant.hub.loginradius.com/service/oidc/{app}/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={authorization_code}
&redirect_uri=https://client.example.com/callback
&client_id=https://client.example.com/.well-known/oauth/client-metadata.json
&code_verifier={pkce_code_verifier}
&resource=https://mcp.example.com/mcp

Step 11: Authorization Server validates the code and PKCE verifier, then returns tokens:
```
{
  "access_token": "{access_token}",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "{refresh_token}"
}
```
No client_secret is issued or required because this is a public client.

Step 12: MCP Client calls MCP tools using the access token:

POST https://mcp.example.com/mcp
Authorization: Bearer {access_token}
Content-Type: application/json

{ "method": "tools/list" }

Step 13: MCP Server validates the token and processes the MCP request.
Step 14: MCP Server returns the MCP response.

For a comparison of CIMD vs DCR fields, see the CIMD vs DCR table.