Agentic Data Plane

Configure User-Delegated OAuth

User-delegated OAuth means each end-user authenticates against the MCP server’s upstream system (for example, Slack, Jira, Google) with their own credentials. Redpanda stores their token in the token vault and injects it at call time. Contrast with service-account OAuth, where one shared identity is used for every caller.

After completing this guide, you will be able to:

  • Configure an MCP server to use user-delegated OAuth with a registered OAuth provider

  • Walk an end-user through the consent flow and verify the connection

  • Troubleshoot scope upgrades, token expiry, and refresh failures

Prerequisites

  • An OAuth provider resource configured in Redpanda Agentic Data Plane on the Outbound providers tab of Integrations setup. The provider declares the upstream’s authorize_url, token_url, supported scopes, and client credentials. See Configure an OAuth Provider.

  • The required scopes for the upstream API you plan to call.

  • For self-managed MCP servers: the server URL must be https:// (proto rule remote_mcp.user_oauth_requires_https). HTTP is rejected at create time.

  • For managed MCP servers: the type must support user-delegated OAuth. SQL doesn’t; Slack, Jira, and Google managed types do. Check Managed catalog before configuring.

Configure the server

  1. Create or edit your MCP server (see Create an MCP Server).

  2. In the authentication section, choose User-delegated OAuth.

  3. Pick the configured OAuth provider (UserOAuthAuth.provider_name).

  4. List the required scopes (UserOAuthAuth.required_scopes). Redpanda enforces these at consent time.

  5. (Optional) Override token injection through the API or CLI. By default Redpanda sends Authorization: Bearer <token>. To use a different header, set TokenInjection.header_name. To omit the prefix entirely (for example, an upstream that expects a bare API key as the token), set TokenInjection.header_prefix to the empty string. The create form doesn’t expose these fields; the UI’s user-delegated authentication section takes only the OAuth provider and required scopes.

  6. Save.

Choosing user-delegated OAuth instead of service-account OAuth is the credential-mode decision: there’s no separate field. User-delegated gives each caller a per-user upstream identity; service-account gives every caller one shared identity. Switching between them later requires re-consent for every active user.
To configure user-delegated OAuth from the CLI, use --user-oauth-provider and --user-oauth-scopes on rpk ai mcp create or rpk ai mcp update. See Create an MCP Server.

The user connection flow

The first time a user calls a tool that needs this server’s authentication, Redpanda doesn’t have a stored token for them. The behavior is:

  1. The MCP RPC returns FAILED_PRECONDITION with an OAuthConnectionRequired error detail. The detail carries an authorize_url.

  2. Agentic Data Plane surfaces a consent prompt to the user, pointing at the authorize_url.

  3. The user completes the device-authorization flow with the upstream provider.

  4. The upstream provider redirects back to Redpanda with a token. Redpanda stores it in the token vault under that user’s identity.

  5. The original tool call retries automatically. Subsequent calls reuse the stored token.

After consent, the user can see and revoke their connection under My Connections in Agentic Data Plane.

Manage your connections

The My Connections page in the sidebar is each user’s view of their own third-party connections, so a user can authorize the providers their MCP servers need without waiting for a tool call to trigger the consent flow. It shows connections for your own identity only.

The page uses a two-pane layout. The left rail lists providers grouped by status:

  • Available to connect: Providers you haven’t authorized yet.

  • Connected: Providers with a usable connection.

  • Needs attention: Connections that have failed, or whose refresh token is close to expiring, and need to be reconnected.

Select a provider to open its detail pane on the right. The pane shows the granted scopes, a status badge (Connected, Needs attention, Action required, or Not connected), and the actions for that provider: Connect runs the consent flow and stores a token in the vault under your identity, Reconnect re-runs consent for an existing connection (for example, to grant additional scopes or recover after a refresh token expires), and Disconnect revokes it. A connection that the gateway can renew automatically from a stored refresh token stays Connected with no action from you; it moves to Needs attention or Action required only when it can no longer renew on its own.

Connections are per-user. Each user authorizes their own accounts, and one user’s connections are not visible to or usable by another.

Scope upgrades

If a user’s stored connection has fewer scopes than the server’s required_scopes, the gateway returns a scope_upgrade_required error and surfaces a new authorize_url requesting the additional scopes. The user re-consents; the connection is updated in place.

Refresh and expiry

Redpanda transparently refreshes tokens before they expire, using the refresh token returned at consent time. A connection is only considered expired when its access token has lapsed and the gateway can no longer renew it automatically. As long as a usable refresh token is stored, the connection stays active across access-token expiry, and the gateway renews access silently on the next call. This matters for upstreams that issue short-lived access tokens with long-lived refresh tokens: a GitHub App, for example, issues 8-hour access tokens backed by refresh tokens that last around six months, so an idle connection stays active for months rather than showing as expired within hours.

A connection is reported as expired, meaning the user must reconnect, only when the access token has lapsed and no usable refresh token exists: either none was stored, or the refresh token itself has expired. When that happens, the next tool call returns OAuthTokenExpired with a reason, and the user must re-consent through the same flow as the initial connection.

Each connection reports whether a refresh token backs it, so a client can tell a connection that renews automatically from one that needs reconnecting. The OAuthConnectionService.ListConnections and GetConnection responses expose this on the Connection message through two read-only fields: refresh_token_present (a refresh token is stored, so the gateway renews access automatically) and refresh_token_expires_at (when the refresh token itself expires, if the upstream reports it, as GitHub Apps do; absent when unknown or non-expiring).

Service-account OAuth contrast

If you want one shared upstream identity for every caller (instead of per-user identities), choose Service-account OAuth on the server instead of User-delegated OAuth. With service-account OAuth, every caller of every tool sees the same upstream identity; the upstream system has no idea which Agentic Data Plane user invoked the tool. With user-delegated OAuth, the upstream system sees each end-user as themselves and applies their own permissions.

For the field-by-field service-account-OAuth setup, see create-server.adoc.

Worked examples

  • Slack: consumer-facing user-delegated OAuth example. Shows the consent flow against a real Slack workspace.

  • Jira: enterprise user-delegated OAuth example. Atlassian’s OAuth flow differs from Slack’s; this page calls out scope-management gotchas.

Troubleshooting

Symptom What to check

"OAuth provider not found"

The provider name on the server doesn’t match an OAuth provider in Agentic Data Plane. Check spelling and that the provider exists.

"HTTPS required" on save (self-managed only)

User-delegated OAuth requires https:// URLs on the MCP server (proto rule remote_mcp.user_oauth_requires_https). Switch the server’s URL to HTTPS.

OAuthConnectionRequired returned even after the user consented

The user’s vault entry might have been revoked or the token expired with no refresh. Have the user re-consent through My Connections.

scope_upgrade_required returned

The required scopes on the server changed (or the user originally consented with fewer scopes). The user re-consents with the higher scope.

My Connections shows stale entries

Connections persist until manually revoked. Have the user disconnect and reconnect the connection if upstream credentials changed.

Next steps