Agentic Data Plane

Connect Remote MCP Clients

External MCP clients (Claude Desktop, ChatGPT desktop, Gemini Apps, Cursor) connect to MCP servers hosted in AI Gateway by registering as OAuth clients. 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:

  • Register an OAuth Client in AI Gateway so an external chat app can authenticate users

  • 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 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 for the outbound authentication side.

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

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 chat client gets a client_id + client_secret it uses to negotiate access tokens. 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.

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.

  • The MCP server’s API URL. Copy it from the server’s Overview tab.

  • For user-delegated MCP servers: An OAuth Provider configured for the upstream system. See Configure an OAuth Provider.

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

Register an OAuth Client in AI Gateway

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

  1. 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.

  2. Click Register Client.

  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.

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 MCP server’s API 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. Once approved, the connector becomes invokable in any conversation.

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

The flow mirrors Claude Desktop. ChatGPT, Cursor, Windsurf, Visual Studio Code, Zed, Gemini CLI, and mcp-remote bridge have catalog presets in the Register Client 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

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

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 access from their Connections page in ADP.

  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

(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.

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. Once a user picks Always allow for a tool, Claude won’t prompt again for that tool from that connector.
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

Maintain registered OAuth Clients without re-creating them:

  • List registered clients: Open OAuth Clients in the sidebar. 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).

  • 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

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 OAuth Clients in the sidebar 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:

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.

Already-issued short-lived access tokens may continue to work until their natural expiry, typically a few minutes. The revocation invalidates refresh tokens, so once 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

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 API URL on the MCP server’s Overview 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

  • 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 Register an OAuth Client 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.

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

  • MCP server authoring: See Create an MCP Server for the server side.

Next steps