Agentic Data Plane

Create an MCP Server

Create MCP servers to give agents structured access to your databases, queues, CRMs, and other business systems. Each server exposes tools, resources, and prompts that an agent can discover and invoke. Choose managed types that Redpanda hosts for you, or register self-managed servers you host yourself.

After completing this guide, you will be able to:

  • Create a managed or self-managed MCP server in Agentic Data Plane

  • Configure each authentication mode and pick the right one for your use case

  • Save the server, verify the API URL, and confirm tools were discovered

Prerequisites

  • For any authentication mode that uses upstream credentials: the credentials in hand and a secret already created in the Redpanda Agentic Data Plane secret store. Secret references must be UPPER_SNAKE_CASE (proto regex ^[A-Z][A-Z0-9_]*$). For example: MCP_API_KEY, OPENAI_API_KEY.

  • For user-delegated OAuth: an OAuth provider resource already configured. See User-delegated OAuth.

Open the MCP Servers page

  1. Open MCP Servers in the sidebar.

  2. Click Create Server.

Pick a backend

The marketplace picker lists every managed type as a card and includes a Remote (Proxied) option for self-managed servers.

  • Managed: Pick a card. Redpanda hosts the server in-process. The configuration form is rendered from the type’s protobuf schema; field labels and help text come straight from the proto.

  • Self-managed: Pick Remote (Proxied). You provide a URL and a transport, and Redpanda proxies requests to your server.

For a tour of every managed type and which one fits your use case, see Managed catalog. To go deep on the self-managed path (transport choices, TLS, multi-server aggregation), see Register a self-managed server.

Name and basic fields

Every server has the same identity fields.

Field Required Notes

Name

Yes

Lowercase letters, numbers, and hyphens only (proto regex ^[a-z][a-z0-9-]*$); 1–63 characters; must start with a letter. Immutable after create. Used as the URL path segment.

Description

No

Up to 256 characters. Shown in list and detail views.

Enabled

Yes (toggle)

Disabled servers reject every tool call.

The name is the server’s identifier and is immutable. The update API preserves it: you can’t rename a server after create. To use a different name, delete the server and create a new one.

Configure the managed flow (managed types only)

Each managed type ships its own configuration schema. The form on this page is rendered from the type’s _config.proto, so field labels and help text come directly from the proto definition. No per-type hand-written form code is required.

For per-type fields, see the Managed catalog: a reference of every managed MCP type Redpanda hosts, grouped by category, with a description and a link to its setup guide where one exists.

MCP enforces a 64-character limit on tool names. For managed MCP types whose generated names exceed that limit, Agentic Data Plane truncates the prefix and replaces it with a hash, so the long-form name becomes something like 64ghux5adn_github_read_v1_GitHubReadService_GetAuthenticatedUser. Agentic Data Plane always preserves the version, service, and method suffix, so the short tool name an agent sees (for example, get_authenticated_user) stays stable across truncations.

You don’t configure the truncation. This detail matters only when you correlate tool calls in logs or transcripts against the generated proto names.

Configure the self-managed flow (Remote/Proxied only)

Two fields on top of the identity fields:

Field Required Notes

URL

Yes

Endpoint URL of your server. Must start with http:// or https://. HTTPS is required if you choose user-delegated OAuth (proto rule remote_mcp.user_oauth_requires_https).

Transport

Yes

SSE (server-sent events) or Streamable HTTP (newer bidirectional protocol). Pick whichever your server speaks. See Register a self-managed server for how to test which transport your server uses.

Configure authentication

Both managed and self-managed servers offer the same set of authentication modes. Managed types only show the modes that make sense for that type; for example, SQL never offers user-delegated OAuth.

Mode Use when

None

The upstream server doesn’t need authentication, or the managed type wraps an in-process resource that needs no creds.

Static key

Single shared API key. Provide a key_ref (secret reference, UPPER_SNAKE_CASE) and an optional header_name (defaults to Authorization).

Token passthrough

Forward the caller’s Authorization header to the upstream server as-is. Use this mode when the upstream already validates upstream tokens.

Service-account OAuth

2-legged OAuth client credentials. One shared upstream identity for every caller. Provide client_id, client_secret_ref, token_url, and any required scopes.

User-delegated OAuth

Each end-user authenticates against the upstream system with their own credentials, and Redpanda injects the user’s token at call time. Pick the configured OAuth Provider and the required scopes. The first time a user calls a tool that needs this server, Redpanda surfaces a consent prompt; Redpanda stores the resulting connection in the token vault, where it shows up under Connections. See User-delegated OAuth for the full flow.
Choosing between Service-account OAuth and User-delegated OAuth is the credential-mode decision. Service-account authentication gives every caller the same identity at the upstream; user-delegated authentication gives each caller their own.

Code mode (optional)

Toggle Code mode to add {name}_search and {name}_execute tools alongside the server’s own tools. Agents can use _search to discover available tools and _execute to run sandboxed Python or JavaScript that orchestrates them. This is useful when you’d rather have the agent generate a small program than call tools one at a time.

When code mode is enabled, the server’s detail page surfaces a second URL, the code-mode MCP URL, that clients can connect to instead of the standard one.

Defer advanced code-mode patterns (sandboxing limits, runtime selection, dependency management) to follow-up content; this page covers only enabling it.

Save and verify

  1. Click Create. The server appears in the list with a Type badge: Managed or Self-managed.

  2. Open the detail page. The Overview tab shows the API URL: this is the MCP URL agents connect to. Copy it for use later.

  3. Open the Connection tab to see ready-to-paste connection snippets, pre-filled with this server’s API URL, for common MCP clients such as Claude Code, Claude Desktop, and Cursor, plus code examples in several languages. The code examples authenticate with the OAuth authorization-code flow and surface the OAuth client ID to use.

  4. Open the Inspector tab. Redpanda performs a live tools/list against the server and lists every tool it discovered. See Test a server’s tools for how to call them.

A populated tools list confirms that the connection works and credentials resolve correctly. If the list is empty or the tab shows an error, see Troubleshooting.

Create from the CLI

Use rpk ai for a non-UI path through the same create flow, useful for scripting and CI.

# Managed type (Workday example)
rpk ai mcp create --name workday-hr \
  --managed-config '{
    "@type": "type.googleapis.com/redpanda.mcps.workday.v1.WorkdayMCPConfig",
    "tenant": "acme",
    "host": "wd2-impl-services1.workday.com",
    "oauth_refresh_token": {
      "username": "isu_user@acme",
      "password_secret_ref": "${secrets.WORKDAY_PASSWORD}",
      "refresh_token_secret_ref": "${secrets.WORKDAY_REFRESH_TOKEN}"
    }
  }'

# Managed type with user-delegated OAuth inside the managed config
# (NetSuite example)
rpk ai mcp create --name netsuite \
  --description "NetSuite ERP with user OAuth" \
  --managed-config '{
    "@type": "type.googleapis.com/redpanda.mcps.netsuite.v1.NetSuiteMCPConfig",
    "accountId": "1234567_SB1",
    "userOauth": {
      "providerName": "netsuite",
      "requiredScopes": ["rest_webservices"]
    }
  }'

# Self-managed server with user-delegated OAuth
rpk ai mcp create --name github-proxy \
  --url https://mcp.example.com/sse \
  --user-oauth-provider github \
  --user-oauth-scopes repo,read:org

# Update a self-managed server's user-delegated OAuth scopes
rpk ai mcp update github-proxy \
  --user-oauth-provider github \
  --user-oauth-scopes repo,read:org,workflow
Flag Notes

--managed-config

JSON blob carrying the managed type’s _config.proto shape, including a @type URL.

--user-oauth-provider

Self-managed servers only. Name of an OAuth Provider already registered under OAuth Providers. See Configure an OAuth Provider. The principal needs dataplane_aigateway_oauthprovider_attach on the named provider (AI-893). Managed servers that support user-delegated OAuth carry their auth shape inside --managed-config.

--user-oauth-scopes

Self-managed servers only. Comma-separated scopes the server requires. Provide every scope any tool may need; user re-consent is required if scopes change later.

The command targets the AI Gateway of your selected Agentic Data Plane environment, using credentials from rpk ai auth login.

List and filter servers with the API

To enumerate MCP servers programmatically, call MCPServerService.ListMCPServers. Beyond the name_contains substring match, the request accepts an AIP-160 filter expression and an AIP-132 order_by, so you can scope and sort the list on the server (for example, to page through only the managed servers, newest first) instead of filtering the loaded page.

The list endpoint uses the same OIDC client-credentials authentication as the rest of AI Gateway. Mint a service-account access token using the flow in Authenticate with OIDC client credentials, then pass it as a bearer token. The service account needs dataplane_adp_mcpserver_list.

The request’s filter object carries two independent fields:

Field Meaning

name_contains

Case-insensitive substring match on the server name.

filter

AIP-160 expression (maximum 1024 characters) that the server ANDs with name_contains and the tenant scope. Filterable columns: name, type, enabled, description, created_at, and updated_at. Use it for multi-value OR semantics, for example type = "MCP_SERVER_TYPE_REMOTE" OR type = "MCP_SERVER_TYPE_MANAGED". The type column accepts the MCPServerType enum values MCP_SERVER_TYPE_REMOTE and MCP_SERVER_TYPE_MANAGED; enabled accepts true or false.

Set order_by (maximum 256 characters) to a comma-separated list of fields, each optionally suffixed with ` desc` (ascending by default), for example created_at desc. Orderable fields are the keyset columns name and created_at. An unsupported field returns InvalidArgument. Leave order_by empty to use the server default (created_at desc). The order is encoded into the page token, so keep it stable across a paged walk.

ACCESS_TOKEN="<oidc-access-token>"   # from the client_credentials flow
DATAPLANE_BASE="https://aigw.<cluster-id>.clusters.rdpa.co"

curl -s --request POST \
  --url "${DATAPLANE_BASE}/redpanda.api.adp.v1alpha1.MCPServerService/ListMCPServers" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": { "filter": "type = \"MCP_SERVER_TYPE_MANAGED\"" },
    "order_by": "created_at desc",
    "page_size": 50
  }' | jq

The response carries the matching mcp_servers, a next_page_token for the next page, and an estimated total_size (AIP-158) of all servers matching the filter, ignoring pagination.

Edit, disable, and delete a server

  • Edit: most fields can change. The name and type are immutable after create.

  • Disable: toggle Enabled off. The server stays in the list, but every tool call returns an error until you re-enable it.

  • Delete: permanently removes the server record. User OAuth connections are scoped to the OAuth Provider, not the server, so they stay in the token vault and keep working for other servers that use the same provider. If you re-create a server against the same provider, users don’t re-consent unless the new server requires additional scopes.

Troubleshooting

Symptom What to check

Secret <NAME> not found

The secret reference is case-sensitive and must be UPPER_SNAKE_CASE matching the proto regex ^[A-Z][A-Z0-9_]*$. Confirm the secret exists in the Agentic Data Plane secret store and is spelled identically.

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

You picked user-delegated OAuth on a server with an http:// URL. Switch to https:// (proto rule remote_mcp.user_oauth_requires_https).

Inspector / tools list empty after create

The connection or authentication might be failing. Check the Connection tab for upstream errors. For self-managed, confirm the transport (SSE vs. Streamable HTTP) matches what your server actually speaks.

Tool calls return errors after disable/enable

Disabled servers reject all tool calls. Confirm the Enabled toggle is on.

Next steps