Skip to content
AuthAction Documentation

Client ID Metadata Documents

An MCP client usually has no prior relationship with your AuthAction tenant. Instead of creating an application for every client a user might connect with, AuthAction supports Client ID Metadata Documents, the approach the MCP authorization specification recommends.

The client uses an HTTPS URL as its client_id. That URL serves a small JSON document describing the client. AuthAction fetches the document when the client first connects, checks it, and stores a copy.

How it works

Section titled “How it works”

  1. The MCP client starts an authorization request with its metadata URL as the client_id and your MCP server as the resource:

    GET /oauth2/authorize?
      response_type=code&
      client_id=https://claude.ai/oauth/claude-code-client-metadata&
      redirect_uri=http://localhost:53682/callback&
      resource=https://mcp.example.com&
      code_challenge=...&
      code_challenge_method=S256&
      state=...

  2. AuthAction checks that the resource is an API with MCP Client Access enabled, and, if the API only allows chosen clients, that this client_id is one of them. Otherwise the request is rejected before anything is fetched.

  3. AuthAction fetches the document at the client_id URL and validates it.

  4. The redirect_uri must match one of the document’s redirect_uris.

  5. The user signs in with one of the connections you enabled for MCP clients, and the client exchanges the code for tokens using PKCE.

The client then appears under Applications with an MCP badge. You do not need to create it.

The metadata document

Section titled “The metadata document”

A client publishes a document like this one, served as application/json:

{
  "client_id": "https://claude.ai/oauth/claude-code-client-metadata",
  "client_name": "Claude Code",
  "client_uri": "https://claude.ai",
  "redirect_uris": ["http://localhost/callback", "http://127.0.0.1/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

AuthAction accepts a document when:

  • The client_id URL uses https, has a path, uses a domain name rather than an IP address, and has no fragment or credentials.
  • The client_id inside the document is exactly the URL it was fetched from.
  • redirect_uris is present. http redirect URIs are only allowed on loopback addresses (localhost, 127.0.0.1, [::1]).
  • The client is public: token_endpoint_auth_method is none or absent, and the document contains no client_secret.
  • grant_types, when present, includes authorization_code.

Redirect URI matching

Section titled “Redirect URI matching”

Redirect URIs are matched exactly. Wildcards are never applied to a published document.

For loopback redirect URIs the port is ignored, as RFC 8252 requires. Native clients like Claude Code listen on a random port, so http://localhost/callback in the document matches http://localhost:53682/callback in the request.

Caching

Section titled “Caching”

AuthAction keeps the stored copy for as long as the document’s Cache-Control: max-age allows, between 5 minutes and 24 hours. It uses 1 hour when no header is set. The document is fetched again on the next authorization after that, so a client that changes its redirect URIs is picked up automatically.

Deleting the client under Applications clears the stored copy. It is fetched again the next time the client connects.

Discovery

Section titled “Discovery”

AuthAction’s discovery document at /.well-known/openid-configuration includes:

"client_id_metadata_document_supported": true

MCP clients read this to decide to use their metadata URL as the client_id.

Publishing a document for your own client

Section titled “Publishing a document for your own client”

If you are building an MCP client:

  1. Host the JSON above on a stable HTTPS URL you control, for example https://yourapp.com/oauth/client-metadata.json.
  2. Set client_id in the document to that exact URL.
  3. List every redirect URI your client uses.
  4. Use that URL as client_id in authorization and token requests, and always send a PKCE code_challenge.
Section titled “Related”