From 2fdc4d0ee4137035bfb7ab1eb7d1d7fc9a658648 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 1 Jul 2026 12:19:54 +0000 Subject: [PATCH 1/5] docs(connect): document Dynamic Client Registration for remote MCP clients AI Gateway now enables OAuth 2.0 Dynamic Client Registration (RFC 7591) globally, so its authorization-server metadata advertises a registration_endpoint and spec-conformant MCP clients (Claude Code, Cursor, ChatGPT) can self-register instead of requiring a manually provisioned OAuth client. Update the remote MCP clients guide to: - Add a section covering how to enable per-tenant self-registration with `rpk ai oauth-client dcr`, the open and initial-access-token admission modes, registration caps and rate limits, Initial Access Token lifecycle, and how to review DCR-issued clients. - Point the manual registration section at the self-registration path. - Remove the outdated "No Dynamic Client Registration" limitation. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01JQB7JbF6ZT53Jx2J5RchsZ --- modules/connect/pages/remote-mcp-clients.adoc | 100 +++++++++++++++++- 1 file changed, 98 insertions(+), 2 deletions(-) diff --git a/modules/connect/pages/remote-mcp-clients.adoc b/modules/connect/pages/remote-mcp-clients.adoc index f7b79ba..f56e8e8 100644 --- a/modules/connect/pages/remote-mcp-clients.adoc +++ b/modules/connect/pages/remote-mcp-clients.adoc @@ -74,6 +74,8 @@ Before you wire up the chat-client connector, make sure you have: == Register an OAuth Client in AI Gateway +Register a client by hand when it can't self-register, when it needs a confidential `client_secret`, or when you want to pre-provision it before the first connection. For spec-conformant clients that support Dynamic Client Registration, you can skip this manual flow and let them register themselves. See <>. + Create an OAuth Client to give the chat app the credentials it needs to authenticate against AI Gateway: . Open *OAuth Clients* in the sidebar. The page lists every external tool registered to request access tokens from this gateway, with its `Name`, `Grant Types`, `Status`, and `Scopes`. @@ -119,6 +121,102 @@ On submit, AI Gateway mints the `client_id`. Confidential clients (those using a // TODO: capture screenshots of the Register Client catalog, the custom form, and the post-create detail page. +[[self-register-with-dcr]] +== Let clients self-register with Dynamic Client Registration + +Instead of registering every client by hand, you can let spec-conformant MCP clients register themselves. AI Gateway supports OAuth 2.0 Dynamic Client Registration (DCR, RFC 7591) and advertises a `registration_endpoint` in its authorization-server metadata at `/.well-known/oauth-authorization-server`. Clients that read this metadata (Claude Code, Cursor, ChatGPT, and other spec-conformant MCP clients) register on their first connection attempt, run authorization-code and PKCE, and obtain tokens without an admin provisioning a `client_id` or `client_secret` first. + +Self-registration is off for each organization by default. Enable it before conformant clients can register. + +=== Enable self-registration + +Run the `rpk ai oauth-client dcr update` command to enable DCR and choose how callers are admitted: + +[source,bash] +---- +rpk ai oauth-client dcr update --enabled --admission-mode open +---- + +Inspect the current policy at any time: + +[source,bash] +---- +rpk ai oauth-client dcr get +---- + +The command reports whether DCR is enabled, the admission mode, and the resource and rate caps, for example `ENABLED: true`, `ADMISSION_MODE: OPEN`, `ALLOWED_RESOURCES: ["*"]`. + +=== Admission modes + +The admission mode controls who may register once DCR is enabled: + +[cols="1,3"] +|=== +|Mode |Behavior + +|`open` +|Any spec-conformant client registers without credentials. Use this for clients that register anonymously, such as Claude Code. The registration rate limit and client cap still apply. + +|`initial-access-token` +|Callers must present an admin-minted, one-shot bearer token (an Initial Access Token) on the registration request. Use this to keep self-registration open only to holders of a token you hand out. +|=== + +The `software-statement` admission mode is reserved and not yet supported. + +=== Restrict and rate-limit self-registration + +Pass caps to the same `rpk ai oauth-client dcr update` command to bound what self-registered clients can do: + +[cols="1,3"] +|=== +|Flag |Purpose + +|`--allowed-resource` +|MCP server URL that every DCR-issued client may request tokens for. Repeatable. `*` allows any MCP server on the gateway. + +|`--client-cap` +|Maximum number of concurrent DCR-issued clients. + +|`--rate-per-hour` +|Maximum registrations accepted per hour. + +|`--inactive-ttl-days` +|Days of inactivity before AI Gateway removes a DCR-issued client. `0` keeps clients indefinitely. +|=== + +AI Gateway disables and then removes inactive self-registered clients according to this policy, so abandoned registrations don't accumulate. + +=== Mint Initial Access Tokens + +In `initial-access-token` mode, mint a one-shot token and give it to the client operator, who presents it on the registration request: + +[source,bash] +---- +rpk ai oauth-client dcr iat mint --label "Claude handoff" --ttl 24h +---- + +The token's plaintext appears only once, on mint, and is consumed on the first successful registration. List and revoke tokens with: + +[source,bash] +---- +rpk ai oauth-client dcr iat list +rpk ai oauth-client dcr iat revoke +---- + +Replace `` with the ID from the IAT list. + +=== Review self-registered clients + +Self-registered clients appear alongside manually registered ones in the `rpk ai oauth-client list` output and on the *OAuth Clients* page, marked with a DCR badge and a name of the form `dcr-`. They authenticate with PKCE and no client secret. Audit them like any other client, and delete one to revoke its tokens: + +[source,bash] +---- +rpk ai oauth-client list +rpk ai oauth-client delete +---- + +Replace `` with the `dcr-` name from the list. + == Wire up Claude Anthropic supports custom MCP connectors in Claude.ai (web), Claude Desktop, and the Claude organization-settings UI. The setup flow is the same in each: @@ -279,8 +377,6 @@ Common symptoms and fixes: == Limitations -* *No Dynamic Client Registration (RFC 7591)*: AI Gateway does not support OAuth 2.0 Dynamic Client Registration today. Every external MCP client must be registered manually through the *OAuth Clients* page or the `rpk ai oauth-client` CLI before its first connection attempt. MCP clients that *only* support DCR (some experimental connector builds) cannot connect to AI Gateway until a corresponding OAuth Client is registered by an admin. See <> for the manual flow. - This page does not cover: * *Custom desktop or mobile UIs*: Build against the AI Gateway MCP endpoints directly using your platform's HTTP client; you don't need an OAuth Client unless you want the same external-app flow. From ea24f720b72114ee68b6e8c53a0e20a977ab3690 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Wed, 1 Jul 2026 07:41:33 -0600 Subject: [PATCH 2/5] docs(connect): apply review wording fixes to DCR section Address docs-team-standards review suggestions on the Dynamic Client Registration section: clarify the authorization-code flow phrasing and use sentence case for the "Mint initial access tokens" heading. Co-Authored-By: Claude Opus 4.8 (1M context) --- modules/connect/pages/remote-mcp-clients.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/connect/pages/remote-mcp-clients.adoc b/modules/connect/pages/remote-mcp-clients.adoc index f56e8e8..eab3154 100644 --- a/modules/connect/pages/remote-mcp-clients.adoc +++ b/modules/connect/pages/remote-mcp-clients.adoc @@ -124,7 +124,7 @@ On submit, AI Gateway mints the `client_id`. Confidential clients (those using a [[self-register-with-dcr]] == Let clients self-register with Dynamic Client Registration -Instead of registering every client by hand, you can let spec-conformant MCP clients register themselves. AI Gateway supports OAuth 2.0 Dynamic Client Registration (DCR, RFC 7591) and advertises a `registration_endpoint` in its authorization-server metadata at `/.well-known/oauth-authorization-server`. Clients that read this metadata (Claude Code, Cursor, ChatGPT, and other spec-conformant MCP clients) register on their first connection attempt, run authorization-code and PKCE, and obtain tokens without an admin provisioning a `client_id` or `client_secret` first. +Instead of registering every client by hand, you can let spec-conformant MCP clients register themselves. AI Gateway supports OAuth 2.0 Dynamic Client Registration (DCR, RFC 7591) and advertises a `registration_endpoint` in its authorization-server metadata at `/.well-known/oauth-authorization-server`. Clients that read this metadata (Claude Code, Cursor, ChatGPT, and other spec-conformant MCP clients) register on their first connection attempt, run the authorization-code flow with PKCE, and obtain tokens without an admin provisioning a `client_id` or `client_secret` first. Self-registration is off for each organization by default. Enable it before conformant clients can register. @@ -186,7 +186,7 @@ Pass caps to the same `rpk ai oauth-client dcr update` command to bound what sel AI Gateway disables and then removes inactive self-registered clients according to this policy, so abandoned registrations don't accumulate. -=== Mint Initial Access Tokens +=== Mint initial access tokens In `initial-access-token` mode, mint a one-shot token and give it to the client operator, who presents it on the registration request: From 0f0142f8613266ed2be30453ef1a1a2c741c1856 Mon Sep 17 00:00:00 2001 From: micheleRP Date: Wed, 1 Jul 2026 08:36:46 -0600 Subject: [PATCH 3/5] docs(connect): clarify that DCR endpoint is advertised only once enabled The authorization-server metadata advertises registration_endpoint only after DCR is enabled for the organization (disabled tenants return registration_endpoint: null, per adp/aigw DCR-DEMO.md and RFC section 1). Reorder the section intro so the "off by default" fact precedes the endpoint-advertisement claim, matching source behavior. Co-Authored-By: Claude Opus 4.8 (1M context) --- modules/connect/pages/remote-mcp-clients.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/connect/pages/remote-mcp-clients.adoc b/modules/connect/pages/remote-mcp-clients.adoc index eab3154..7f632b2 100644 --- a/modules/connect/pages/remote-mcp-clients.adoc +++ b/modules/connect/pages/remote-mcp-clients.adoc @@ -124,9 +124,9 @@ On submit, AI Gateway mints the `client_id`. Confidential clients (those using a [[self-register-with-dcr]] == Let clients self-register with Dynamic Client Registration -Instead of registering every client by hand, you can let spec-conformant MCP clients register themselves. AI Gateway supports OAuth 2.0 Dynamic Client Registration (DCR, RFC 7591) and advertises a `registration_endpoint` in its authorization-server metadata at `/.well-known/oauth-authorization-server`. Clients that read this metadata (Claude Code, Cursor, ChatGPT, and other spec-conformant MCP clients) register on their first connection attempt, run the authorization-code flow with PKCE, and obtain tokens without an admin provisioning a `client_id` or `client_secret` first. +Instead of registering every client by hand, you can let spec-conformant MCP clients register themselves. AI Gateway supports OAuth 2.0 Dynamic Client Registration (DCR, RFC 7591), but self-registration is off for each organization by default. Once you enable it, the gateway advertises a `registration_endpoint` in its authorization-server metadata at `/.well-known/oauth-authorization-server`. Clients that read this metadata (Claude Code, Cursor, ChatGPT, and other spec-conformant MCP clients) register on their first connection attempt, run the authorization-code flow with PKCE, and obtain tokens without an admin provisioning a `client_id` or `client_secret` first. -Self-registration is off for each organization by default. Enable it before conformant clients can register. +Enable self-registration before conformant clients can register. === Enable self-registration From eb86f93378a93d7e5546ab4d424f1146d66beddf Mon Sep 17 00:00:00 2001 From: micheleRP Date: Wed, 1 Jul 2026 08:50:15 -0600 Subject: [PATCH 4/5] docs(connect): fix wildcard asterisk breaking bold in Allowed MCP Resources row The bare `*` in the monospace default value paired with the `*Restrict*` bold marker later in the cell, so AsciiDoc bolded the wrong span. Use the {asterisk} attribute for the literal wildcard so the code renders `*` and `*Restrict*` bolds correctly. Co-Authored-By: Claude Opus 4.8 (1M context) --- modules/connect/pages/remote-mcp-clients.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/connect/pages/remote-mcp-clients.adoc b/modules/connect/pages/remote-mcp-clients.adoc index 7f632b2..e6cbf85 100644 --- a/modules/connect/pages/remote-mcp-clients.adoc +++ b/modules/connect/pages/remote-mcp-clients.adoc @@ -100,7 +100,7 @@ Create an OAuth Client to give the chat app the credentials it needs to authenti |The exact URIs the gateway redirects to after a user approves. Each chat client publishes its own; a well-known client prefills them. Multiple URIs are allowed. Claude.ai, for example, uses two: `\https://claude.ai/api/mcp/auth_callback` and `\https://claude.ai/api/organizations/custom-connectors/oauth/callback`; Claude Desktop uses `\http://127.0.0.1:54545/callback`. |`Allowed MCP Resources` -|Which MCP servers this client may request tokens for. Defaults to `*` (any MCP server hosted on this gateway). Click *Restrict* to limit the client to specific MCP resource URLs. +|Which MCP servers this client may request tokens for. Defaults to `{asterisk}` (any MCP server hosted on this gateway). Click *Restrict* to limit the client to specific MCP resource URLs. |`Grant Types` |`Authorization Code` (RFC 6749 §4.1) and `Refresh Token` (RFC 6749 §6, rotating single-use). This is the standard combination for browser-based chat clients with long-lived tokens. From bac2095ae16eec3bbc3eb072bb89690eecf1b2ac Mon Sep 17 00:00:00 2001 From: micheleRP Date: Wed, 1 Jul 2026 09:04:03 -0600 Subject: [PATCH 5/5] docs(connect): use "after" instead of "once" in DCR section Per the docs-team-standards terminology list, "once" is ambiguous (one time vs. as soon as); use "after". Applies to the two temporal uses in the self-registration intro and the admission-modes lead-in. Co-Authored-By: Claude Opus 4.8 (1M context) --- modules/connect/pages/remote-mcp-clients.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/connect/pages/remote-mcp-clients.adoc b/modules/connect/pages/remote-mcp-clients.adoc index e6cbf85..16e4186 100644 --- a/modules/connect/pages/remote-mcp-clients.adoc +++ b/modules/connect/pages/remote-mcp-clients.adoc @@ -124,7 +124,7 @@ On submit, AI Gateway mints the `client_id`. Confidential clients (those using a [[self-register-with-dcr]] == Let clients self-register with Dynamic Client Registration -Instead of registering every client by hand, you can let spec-conformant MCP clients register themselves. AI Gateway supports OAuth 2.0 Dynamic Client Registration (DCR, RFC 7591), but self-registration is off for each organization by default. Once you enable it, the gateway advertises a `registration_endpoint` in its authorization-server metadata at `/.well-known/oauth-authorization-server`. Clients that read this metadata (Claude Code, Cursor, ChatGPT, and other spec-conformant MCP clients) register on their first connection attempt, run the authorization-code flow with PKCE, and obtain tokens without an admin provisioning a `client_id` or `client_secret` first. +Instead of registering every client by hand, you can let spec-conformant MCP clients register themselves. AI Gateway supports OAuth 2.0 Dynamic Client Registration (DCR, RFC 7591), but self-registration is off for each organization by default. After you enable it, the gateway advertises a `registration_endpoint` in its authorization-server metadata at `/.well-known/oauth-authorization-server`. Clients that read this metadata (Claude Code, Cursor, ChatGPT, and other spec-conformant MCP clients) register on their first connection attempt, run the authorization-code flow with PKCE, and obtain tokens without an admin provisioning a `client_id` or `client_secret` first. Enable self-registration before conformant clients can register. @@ -148,7 +148,7 @@ The command reports whether DCR is enabled, the admission mode, and the resource === Admission modes -The admission mode controls who may register once DCR is enabled: +The admission mode controls who may register after DCR is enabled: [cols="1,3"] |===