# Connect Remote MCP Clients

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt)

---
title: Connect Remote MCP Clients
latest-operator-version: v26.2.1
latest-console-tag: v3.10.0
latest-connect-version: 4.105.0
latest-redpanda-tag: v26.2.1
docname: remote-mcp-clients
page-component-name: agentic-data-plane
page-version: master
page-component-version: master
page-component-title: Agentic Data Plane
page-relative-src-path: remote-mcp-clients.adoc
page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/remote-mcp-clients.adoc
description: Connect external MCP clients to MCP servers in AI Gateway using client metadata documents, dynamic client registration, or manual registration.
page-topic-type: how-to
personas: agent_builder, platform_engineer, security_compliance_lead
learning-objective-1: Choose a client identification method for an external chat app
learning-objective-2: Wire a custom connector in Claude Desktop (or another chat client) to your MCP server
learning-objective-3: Walk a user through the OAuth flow that runs end-to-end
page-git-created-date: "2026-05-28"
page-git-modified-date: "2026-08-10"
---

<!-- Source: https://docs.redpanda.com/agentic-data-plane/connect/remote-mcp-clients.md -->

External MCP clients (Claude Desktop, ChatGPT desktop, Gemini Apps, Cursor) connect to MCP servers hosted in AI Gateway over OAuth. A client can identify itself with a client metadata document, register itself dynamically, or use a client that an administrator registered manually. End-users get the MCP tools inside their preferred chat app, with Redpanda mediating both client-app authentication and upstream-system authentication.

After completing this guide, you will be able to:

-   Choose a client identification method for an external chat app

-   Wire a custom connector in Claude Desktop (or another chat client) to your MCP server

-   Walk a user through the OAuth flow that runs end-to-end


![OAuth client onboarding options. Client ID metadata documents let a public client use a metadata URL without a stored registration. Dynamic client registration lets a client create and maintain its own registration in AI Gateway. Manual registration lets an administrator enter redirect URIs and distribute credentials for clients that support neither automated option.](https://docs.redpanda.com/agentic-data-plane/connect/_images/oauth-client-onboarding-options.svg)

Figure 1. Choose the lightest client onboarding method the MCP client supports

> ❗ **IMPORTANT**
>
> OAuth clients and OAuth providers govern _opposite directions_ of authentication and are separate resources.
>
> -   An OAuth client (this page) governs _inbound_ authentication: an external chat app (Claude Desktop, ChatGPT, Copilot Studio, Cursor) authenticating to AI Gateway so its users can invoke MCP tools.
>
> -   An OAuth provider governs _outbound_ authentication: AI Gateway authenticating to an upstream system (GitHub, Slack, Salesforce) on a user’s behalf when an MCP server uses user-delegated OAuth.
>
>
> See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/) for the outbound authentication side.

## [](#when-to-use-this)When to use this

Use a remote MCP client connection when:

-   You want users to invoke MCP tools from inside Claude Desktop, ChatGPT desktop, Gemini Apps, or Cursor without writing custom integration code.

-   You already have, or are about to create, an MCP server (managed or self-managed) in AI Gateway.

-   End-users have accounts with the chat client and the upstream system you’re integrating with.


Use a different approach when:

-   You need programmatic, server-side tool invocation. See [Connect your app to AI Gateway](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/) for SDK-based access.

-   You need an in-house chat UI. Build against the AI Gateway’s MCP endpoints directly with the SDK of your choice.


## [](#architecture-how-the-resources-work-together)Architecture: How the resources work together

Wiring a remote chat client to an MCP server uses three resources in AI Gateway:

| Resource | Role |
| --- | --- |
| MCP server | The tool surface itself. Managed (Redpanda hosts it) or self-managed (you host it). See Create an MCP Server. |
| OAuth Provider | Defines how AI Gateway authenticates against the upstream system on behalf of users (for example, GitHub) when the MCP server uses user-delegated OAuth. See Configure an OAuth Provider. Optional: only needed if the MCP server requires per-user upstream identity. |
| OAuth Client | Defines how an external chat app (Claude Desktop, ChatGPT, Gemini, Cursor) authenticates against AI Gateway on behalf of users. The client can use an HTTPS URL as its client_id, register dynamically, or use credentials from a manual registration. This is what makes the chat-client integration possible. |

Putting it together with a GitHub example:

-   The **MCP server** is a managed GitHub MCP, configured to use user-delegated OAuth.

-   The **OAuth Provider** points at GitHub’s OAuth endpoints; AI Gateway uses it to act as each user against GitHub.

-   The **OAuth Client** is registered for Claude Desktop; Claude Desktop uses it to act as each user against AI Gateway.


When a user invokes a tool, AI Gateway runs both authentication handshakes: Claude to AI Gateway through the OAuth Client, then AI Gateway to GitHub through the OAuth Provider.

![Two-stage OAuth flow. An external MCP client authenticates inbound to AI Gateway through an OAuth client. AI Gateway invokes the MCP server, then authenticates outbound to the upstream system through an OAuth provider when user-delegated OAuth is configured.](https://docs.redpanda.com/agentic-data-plane/connect/_images/remote-mcp-client-authentication.svg)

Figure 2. A remote MCP tool call crosses separate inbound and outbound OAuth boundaries

## [](#prerequisites)Prerequisites

Before you wire up the chat-client connector, make sure you have:

-   An MCP server already created in AI Gateway. See [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/).

-   The server’s `Server URL`. Copy it from the server’s **Connection** tab.

-   For user-delegated MCP servers: An OAuth Provider configured for the upstream system. See [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/).

-   End-users have accounts with the chat client (Claude, ChatGPT, Gemini, Cursor) and the upstream system the MCP server connects to.


## [](#client-metadata-documents)Let clients use metadata documents

Client ID metadata documents let a public OAuth client use an HTTPS URL as its `client_id`. The client hosts a JSON metadata document at that URL instead of creating a saved registration on AI Gateway. The document identifies the client and lists its redirect URIs.

When the client starts an authorization request, AI Gateway checks that the document names its own URL and includes the requested redirect URI. Clients that use a metadata document run the authorization-code flow with PKCE and do not use a shared client secret.

Use metadata documents when the external MCP client supports them and you want clients to connect without an administrator creating or maintaining a registration. A client that uses a metadata document does not create an entry in the **Inbound clients** list.

### [](#enable-client-metadata-documents)Enable client metadata documents

1.  Open **Integrations setup** in the sidebar and select the **Inbound clients** tab.

2.  Select **Self-registration**.

3.  Turn on **Accept client metadata documents (CIMD)**.

4.  Under Trusted document domains, choose one of these options:

    -   **Any domain**: Accept a valid metadata document from any HTTPS domain.

    -   **Only these domains**: Accept documents only from the domains you list. A listed parent domain also covers its subdomains.


5.  Under Allowed resources, add the exact MCP URLs these clients may access, or allow any MCP server on the gateway.

6.  Click **Save settings**.


> 📝 **NOTE**
>
> If the settings report that client metadata documents are not active on the gateway, clients cannot use a URL as their client ID yet. Contact the gateway operator before testing the connection.

> ❗ **IMPORTANT**
>
> The domain policy controls which clients may identify themselves to the gateway. The allowed-resources policy separately controls which MCP servers those clients may request tokens for. Restrict both lists when only approved clients should reach specific MCP servers.

If a client does not support metadata documents, use dynamic client registration or create the client manually.

## [](#register-an-oauth-client-in-ai-gateway)Register an OAuth Client in AI Gateway

Register a client by hand when it supports neither client metadata documents nor dynamic client registration, when it needs a confidential `client_secret`, or when you want to pre-provision it before the first connection. For supported public clients, you can skip this manual flow. See [Let clients use metadata documents](#client-metadata-documents) or [Let clients self-register](#self-register-with-dcr).

Create an OAuth Client to give the chat app the credentials it needs to authenticate against AI Gateway:

1.  Open **Integrations setup** in the sidebar and select the **Inbound clients** tab. The tab lists every external tool registered to request access tokens from this gateway, with its `Name`, `Grant Types`, `Status`, and `Scopes`. (The older `/oauth-clients` path still works but redirects here.)

2.  Click **Add external tool**.

3.  Pick a well-known client to prefill its redirect URIs and recommended scopes, or choose **Custom Client** to register one from scratch. The catalog includes **Claude.ai Custom Connectors**, **Claude Desktop**, **ChatGPT**, **Cursor**, **Windsurf**, **Visual Studio Code** (which also covers GitHub Copilot in VS Code), **Zed**, **Gemini CLI**, and **mcp-remote bridge** (a stdio-to-HTTP bridge for clients without native remote OAuth). For any client not in the catalog (for example, the Gemini consumer apps or Microsoft Copilot Studio), use **Custom Client** and paste the redirect URIs the tool publishes.

4.  Fill in the form:

    | Field | Notes |
    | --- | --- |
    | Display name | Human-readable label shown in the UI and on the consent screen, for example Claude.ai Custom Connectors. |
    | Name | Machine identifier, and the OAuth client_id. Lowercase letters, numbers, and hyphens only. Immutable after creation. |
    | Logo URI | Optional HTTPS URL for a logo shown on the consent screen. |
    | Redirect URIs | 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. |
    | 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. |
    | Token Endpoint Auth Method | How the client authenticates to the token endpoint: Client Secret (Basic) (default), Client Secret (POST), or None (PKCE only) for public clients that can’t store a secret. |
    | Require PKCE | Strongly recommended and enforced by default (RFC 7636). Adds an extra layer of security to the consent flow. |
    | Enabled | Whether the client can start new consent flows. Disabled clients reject new flows. |

5.  Click **Register Client**.


On submit, AI Gateway mints the `client_id`. Confidential clients (those using a Client Secret authentication method) also receive a `client_secret`, **shown only once**. Copy it immediately. The OAuth Server Endpoints panel shows the `Authorization Endpoint` and `Token/Refresh Endpoint` (under `/oauth/idp/`) and the `mcp` scope; paste these into the external app’s OAuth configuration.

## [](#self-register-with-dcr)Let clients self-register

For clients that do not support metadata documents, you can let spec-conformant MCP clients register themselves. AI Gateway supports the OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591), but dynamic 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.

### [](#enable-self-registration)Enable self-registration

Run the `rpk ai oauth-client dcr update` command to enable self-registration and choose how callers are admitted:

```bash
rpk ai oauth-client dcr update --enabled --admission-mode open
```

> 💡 **TIP**
>
> You can also review and change self-registration from the UI: on the **Integrations setup** page, open the **Inbound clients** tab and select **Self-registration** to open its settings.

Inspect the current policy at any time:

```bash
rpk ai oauth-client dcr get
```

The command reports whether self-registration is enabled, the admission mode, and the resource and rate caps, for example `ENABLED: true`, `ADMISSION_MODE: OPEN`, `ALLOWED_RESOURCES: ["*"]`.

### [](#admission-modes)Admission modes

The admission mode controls who may register after you enable self-registration:

| 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)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:

| Flag | Purpose |
| --- | --- |
| --allowed-resource | MCP server URL that every self-registered client may request tokens for. Repeatable. * allows any MCP server on the gateway. |
| --client-cap | Maximum number of concurrent self-registered clients. |
| --rate-per-hour | Maximum registrations accepted per hour. |
| --inactive-ttl-days | Days of inactivity before AI Gateway removes a self-registered 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)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:

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

```bash
rpk ai oauth-client dcr iat list
rpk ai oauth-client dcr iat revoke <token-id>
```

Replace `<token-id>` with the ID from the IAT list.

### [](#review-self-registered-clients)Review self-registered clients

Self-registered clients appear alongside manually registered ones in the `rpk ai oauth-client list` output and on the **Inbound clients** tab, marked with a DCR badge and a name of the form `dcr-<id>`. They authenticate with PKCE and no client secret. Audit them like any other client, and delete one to revoke its tokens:

```bash
rpk ai oauth-client list
rpk ai oauth-client delete <client-name>
```

Replace `<client-name>` with the `dcr-<id>` name from the list.

## [](#wire-up-claude)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:

1.  Open **Settings > Connectors** (or **Customize > Connectors** in newer builds; Anthropic surfaces a _Connectors have moved to Customize_ notice during the migration).

2.  Click **Add custom connector**.

3.  Fill in the connector details:

    | Field | Value |
    | --- | --- |
    | Name | Anything that helps the user identify the connector (for example, Redpanda GitHub). Surfaces in Claude’s tool list. |
    | Remote MCP server URL | The server’s Server URL from AI Gateway. Format: https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/<server-name>. |
    | OAuth client ID (optional, under Advanced settings) | The Client ID from the AI Gateway OAuth Client. Required for any MCP server that requires authentication. Leave blank only for public MCP servers that don’t require authentication. |
    | OAuth client secret (under Advanced settings) | The Client Secret from the AI Gateway OAuth Client. Required whenever Client ID is set. |

4.  Click **Add**. The connector appears in the Connectors list with a `CUSTOM` badge.

5.  Click **Connect** on the new connector row. Claude opens a browser tab pointed at AI Gateway’s authorization endpoint. Sign in with your AI Gateway identity provider. After approval, the connector becomes invokable in any conversation.


> 📝 **NOTE**
>
> Anthropic’s modal warns that connectors are user-trust-based; Anthropic doesn’t control which tools developers expose. If you’re publishing a connector for end-users, document the upstream system and scopes clearly so users know what they’re authorizing.

## [](#wire-up-other-chat-clients)Wire up other chat clients

The flow mirrors Claude Desktop. **ChatGPT**, **Cursor**, **Windsurf**, **Visual Studio Code**, **Zed**, **Gemini CLI**, and **mcp-remote bridge** have catalog presets in the **Add external tool** flow that prefill their redirect URIs; the others use a **Custom Client**. The exact menu paths and field labels differ by client:

-   **ChatGPT desktop**: Recent builds support remote MCP custom connectors. Confirm the latest menu path; OpenAI iterates on this surface.

-   **Cursor**: Supports remote MCP servers in recent builds.

-   **Windsurf**: Supports remote MCP servers in recent builds.

-   **Visual Studio Code**: Built-in MCP support, shared with GitHub Copilot in VS Code. Has a catalog preset.

-   **Zed**: Supports remote MCP server OAuth. Has a catalog preset.

-   **Gemini CLI**: Supports MCP server OAuth. Has a catalog preset. This is the command-line tool, distinct from the consumer Gemini apps, which use a **Custom Client**.

-   **mcp-remote bridge**: For stdio-only MCP clients bridged through `npx mcp-remote <url>`. Has a catalog preset.

-   **Gemini apps**: Recent builds support remote MCP custom connectors. Register through **Custom Client**.

-   **Microsoft Copilot Studio**: Recent builds support remote MCP custom connectors registered against an external OAuth 2.0 authorization server. Register through **Custom Client**, and add Copilot Studio’s published redirect URIs to the AI Gateway OAuth Client before connecting.


The required inputs are the same as Claude Desktop: connector name, MCP URL, Client ID, Client Secret. The chat client’s redirect URIs must be registered on the AI Gateway OAuth Client.

## [](#the-oauth-flow)The OAuth flow

When a user calls a tool that needs upstream access, two OAuth handshakes run end-to-end. Most users only see the second one (and only on the very first tool call).

### [](#chat-client-connects-to-ai-gateway)Chat client connects to AI Gateway

This handshake runs **once per user** when the connector is first added.

1.  The user clicks **Connect** in the chat client.

2.  The chat client opens a browser tab at the AI Gateway authorization endpoint, parameterized with the OAuth Client’s `client_id` and one of the registered redirect URIs.

3.  AI Gateway authenticates the user against the configured IdP (Auth0 today, Zitadel later) and presents an Authorize access consent screen. The screen shows:

    -   The OAuth Client’s name (for example, _Claude (GitHub Read demo) wants to access your data_).

    -   The **Resource** being authorized: The MCP server name and URL.

    -   The **Requested permissions**: The gateway’s internal scopes for this handshake (`mcp` and `offline_access`). These are **not** the upstream system’s scopes; the upstream’s scopes appear during the next handshake.

    -   A footer reminding the user that they can revoke this access at any time in their Redpanda dashboard.


4.  The user clicks **Allow**. AI Gateway redirects the chat client back to the redirect URI with an authorization code.

5.  The chat client exchanges the code for an access token and a refresh token, and stores them locally in its credential store.

6.  Subsequent calls to AI Gateway send the access token in `Authorization: Bearer …​`. The chat client refreshes the token automatically when it expires.


### [](#ai-gateway-connects-to-the-upstream-system)AI Gateway connects to the upstream system

(Only for user-delegated MCP servers.)

This handshake runs **once per user, per upstream**. For an MCP server using user-delegated OAuth (GitHub, Slack, Atlassian, Workday, and so on):

1.  The user invokes a tool that requires upstream authentication.

2.  AI Gateway has no stored upstream token for this user yet. The MCP protocol returns a `FAILED_PRECONDITION` response with an `OAuthConnectionRequired` error detail. The detail carries an `authorize_url` pointing at AI Gateway’s OAuth bridge for the configured upstream provider, for example: `https://aigw.<cluster-id>.clusters.rdpa.co/oauth/v1/authorize?provider_name=github&scopes=read:user,repo`.

3.  The chat client renders the link in its response to the user. Inside Claude this appears as a hyperlinked URL with prose telling the user to authorize the upstream connection (for example, _Authorize the GitHub connection first_) before retrying.

4.  The user clicks the link. AI Gateway redirects them to the **upstream system’s own OAuth consent page** (for example, GitHub’s standard authorization UI) listing the requested repositories and scopes.

5.  The user clicks **Authorize** on the upstream’s consent page. The upstream redirects back to AI Gateway with an authorization code. AI Gateway exchanges the code for a token and stores it in its token vault under the user’s identity.

6.  The user tells the chat client they’ve connected. The chat client retries the original tool call, which now succeeds. Subsequent calls reuse the stored upstream token automatically.


After both steps complete, the user can invoke any tool on the MCP server transparently. They re-consent only if scopes change or the refresh tokens expire.

> 📝 **NOTE**
>
> Claude (and other chat clients) layer their own **per-tool consent prompts** on top of the OAuth flow described here. The first time a connector tries to invoke a specific tool, Claude shows a prompt of the form _Claude wants to use {tool\_name} from {connector\_name}_ with **Always allow** / **Deny** buttons. This is the chat client’s own user-trust UX, not an additional AI Gateway authentication step. After a user picks **Always allow** for a tool, Claude won’t prompt again for that tool from that connector.

> 📝 **NOTE**
>
> If the MCP server uses a service-account authentication mode instead of user-delegated OAuth, only Step 1 runs. AI Gateway calls the upstream with one shared identity and the user never sees the upstream consent flow.

## [](#manage-and-rotate)Manage and rotate

Maintain registered OAuth Clients without re-creating them:

-   **List registered clients**: Open **Integrations setup** in the sidebar and select the **Inbound clients** tab. Each row shows the Name, Grant Types, Status, and Scopes.

-   **Edit a client**: Change the display name, logo URI, redirect URIs, allowed MCP resources, grant types, or token endpoint authentication method. The `client_id` is immutable; delete and recreate the client if you need a new one.

-   **Reissue the secret**: The Client Secret is shown only once at creation and can’t be regenerated in place. To issue a new secret, delete and recreate the client, then update every chat client that used it.

-   **Revoke all tokens**: Invalidate every refresh token AI Gateway has issued under this client without deleting the client itself (see [Revoke all tokens](#revoke-all-tokens)).

-   **Delete a client**: Invalidates every active token issued under it. Token revocation runs automatically as part of delete, so users connected through this client are signed out immediately. Every chat-client connector that depends on this OAuth Client breaks until reconfigured against a replacement.


### [](#revoke-all-tokens)Revoke all tokens

Revoking all tokens invalidates every refresh token AI Gateway has issued under an OAuth Client. Use it when you need to force every connected user to sign in again, for example, after a leaked Client Secret, an offboarding event, or a policy change that warrants re-consent.

Revoke from the UI:

1.  Open **Integrations setup** in the sidebar, select the **Inbound clients** tab, and click the client whose tokens you want to revoke.

2.  On the client detail page, click **Revoke all tokens**.

3.  Confirm the action.


Revoke from the CLI:

```bash
rpk ai oauth-client revoke-tokens <client-name>
```

The command prints the number of tokens it revoked, for example `Revoked 12 tokens for OAuth client claude-desktop`. The action is idempotent: a second invocation returns `Revoked 0 tokens for OAuth client claude-desktop` and exits 0.

> 📝 **NOTE**
>
> Already-issued **short-lived access tokens** may continue to work until their natural expiry, typically a few minutes. The revocation invalidates **refresh tokens**, so after the access token expires, the chat client cannot mint a new one and the user is forced to re-authenticate.

When AI Gateway auto-revokes tokens (on Client deletion or on lifecycle events that imply a hard cut), the same flow runs server-side without the explicit CLI or button click.

Deletion revokes tokens at both levels. Deleting an OAuth client revokes that client’s refresh tokens. Deleting an upstream OAuth provider revokes every active token issued for that provider across all users before it removes the provider config.

## [](#troubleshooting)Troubleshooting

Common symptoms and fixes:

| Symptom | What to check |
| --- | --- |
| Couldn’t connect to MCP server or connector setup fails immediately | The MCP URL is wrong, or the Client ID + Client Secret don’t match an OAuth Client. Confirm the Server URL on the MCP server’s Connection tab and the credentials on the OAuth Client’s detail page. |
| redirect_uri_mismatch during the connect flow | The chat client’s callback URL isn’t registered on the OAuth Client. Add the URL the chat client publishes (Claude Desktop has two; check Claude’s docs for the current set). |
| Connector authorized but no tools appear | The MCP server has zero tools, or tools/list failed at connection time. Open the server in the Inspector to confirm tools are discovered. See Test a server’s tools. |
| Tool call returns an authorize link to the user | First call from a user with no stored upstream token. The user follows the link, completes upstream consent, and the call retries automatically (Step 2 of the flow above). |
| scope_upgrade_required from a tool call | The MCP server’s required_scopes was extended after the user consented at the upstream. The user re-consents at the upstream with the higher scope. |
| 401 Unauthorized from every call after working previously | The chat client’s access token expired and the refresh token also expired (or the OAuth Client secret was rotated). Disconnect the connector and re-add it to mint fresh tokens. |

## [](#limitations)Limitations

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.

-   **Agent-to-agent calls (A2A)**: See the Agents docs; remote MCP clients are end-user-facing.

-   **MCP server authoring**: See [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/) for the server side.


## [](#next-steps)Next steps

-   [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/)

-   [Configure an OAuth Provider](https://docs.redpanda.com/agentic-data-plane/connect/oauth-providers/)

-   [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/)