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 ADP

  • 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 ADP 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]$); 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, ADP truncates the prefix and replaces it with a hash, so the long-form name becomes something like 64ghux5adn_github_read_v1_GitHubReadService_GetAuthenticatedUser. ADP 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 resolves the gateway URL from your active rpk cloud profile and reads the cached rpk cloud login token.

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