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 server 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. For example: MCP_API_KEY, OPENAI_API_KEY.

  • For user-delegated OAuth on a managed server, or to attach an existing provider on a self-managed server: an OAuth provider resource already configured. See User-delegated OAuth.

  • For automatic OAuth setup on a self-managed server: nothing, when the server accepts a client metadata document or supports dynamic client registration. If it supports neither, an OAuth app registered with the upstream vendor, its client ID, and a client-secret reference for a confidential app.

Open the MCP servers page

  1. Open MCP servers in the sidebar.

  2. Click Add MCP server.

Pick a backend

The marketplace picker lists the available managed types as cards and includes a Remote (Proxied) option for self-managed servers.

  • Managed: Click a card. Redpanda hosts the server in-process.

  • Self-managed: Click Remote (Proxied). You provide a server 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), see Register a self-managed server.

Name and basic fields

The create form’s Identity section has two fields. Both managed and self-managed servers use them, and the form suggests a name that you can replace.

Field Required Notes

Name

Yes

Use lowercase letters, numbers, and hyphens only. Use 1 to 63 characters, starting with a letter. Immutable after create. Used as the URL path segment.

Description

No

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

A server created in the UI is enabled as soon as you create it. To rename a server, delete it and create a new one. To label the server for searching and for access policies, see Tags.

Configure the managed flow (managed types only)

For per-type fields, see the Managed catalog. It’s 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 method name, 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 full tool names.

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

The Connection section has two fields on top of the identity fields.

Field Required Notes

Server URL

Yes

Endpoint URL of your server. Must start with http:// or https://. HTTPS is required if you choose user-delegated OAuth or service-account OAuth. User-delegated OAuth has one exception, for cluster-local servers where cluster-local addressing has been enabled for your environment. See Register a self-managed server.

Transport

Yes

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

Configure authentication

Self-managed servers use the authentication modes in this table. A managed type sets up authentication in its own configuration. It can offer some of the same modes and shows only the options that make sense for that type. For example, SQL never offers user-delegated OAuth.

Mode Use when

No Authentication

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

Static Key

Single shared API key. Provide a Key reference (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 server validates the same token your client already holds.

OAuth (Service Account)

2-legged OAuth client credentials. One shared upstream identity for every caller. Provide the Client ID, Client secret reference, Token URL, and any required Scopes.

User OAuth (Per-User Delegated)

Each end user authenticates against the upstream system with their own credentials, and Redpanda injects the user’s token at call time. For a self-managed server, Redpanda can set up OAuth automatically from the server URL, or you can attach an OAuth provider your organization already registered. A managed type that supports this mode attaches an OAuth provider in the type’s configuration. 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.

The Amazon Web Services (AWS) types, such as AWS S3 and AWS SQS, use none of these modes. They authenticate by using AWS access keys or by assuming an AWS Identity and Access Management (IAM) role, as described in AWS Managed MCP Servers.

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)

Turn on Enable code mode to serve a second endpoint for this server, the server URL with a -code suffix, that exposes two tools, search and execute, instead of the server’s full tool catalog. The server’s primary endpoint is unchanged. An agent uses search to find tools by name or description and execute to run sandboxed JavaScript that calls them. This is useful when you’d rather have the agent generate a small program than call tools one at a time. See Code Mode.

The toggle starts on for some managed types, such as OpenAPI and communication types, and off for self-managed servers. Check it before you create the server.

When code mode is enabled, the Connection tab surfaces a second URL, the Code mode URL, that clients can connect to instead of the standard one.

Output format (optional)

By default, a server forwards each tool’s results to the agent as JSON. To reduce the number of tokens an agent spends reading large, tabular results, set the server’s Output format to a token-optimized encoding.

In the Output format section, set Encoding to one of these values:

Encoding Result

JSON (default)

Forwards results to the agent unchanged.

TOON (token-optimized)

Re-encodes tabular and nested-object results into a denser TOON representation that uses fewer tokens than JSON.

JTON (token-optimized)

Re-encodes tabular results into JTON, a compact superset of JSON.

The encoding applies to managed servers, and to a self-managed server on either transport.

The gateway re-encodes a result only when it can do so without losing data. When a result isn’t tabular, can’t be converted losslessly, or is too large to re-encode, the gateway forwards the original JSON unchanged, so changing the encoding never drops or corrupts a result. To change the encoding later, edit the server.

The selected encoding takes effect after token-optimized output is enabled for your gateway. Until then, results are forwarded as JSON.

Output format is a preview capability.

Tags (optional)

The Tags section, last on the create form, takes key/value pairs that organize and filter servers and that access policies can read in their conditions. Enter a tag key and a tag value, then press Enter or click the add (+) button.

To change a server’s tags later, edit the server and use the same Tags field. A tagged server shows its tags on the Overview tab and in the Tags column of the MCP servers list. A narrow window hides that column first.

You can also set tags from the terminal, with the --tags flag on rpk ai mcp-server create and rpk ai mcp-server update.

For the limits and rules that apply to tags on every resource, see Tag Resources.

Save and verify

  1. Click Create server. The server’s detail page shows a Managed or Remote badge next to its name. The Overview tab summarizes the server, including its discovered tools, attached agents, and server metadata.

  2. If your organization has the Activity tab enabled, open it to review how agents have used this server. The Recent calls table lists recent tool calls across the agents attached to this server over the last seven days, showing each call’s time, tool, agent, caller, duration, and status. Click Refresh to reload the feed. If no traffic has run yet, the tab is empty.

  3. Open the Connection tab to get the Server URL that clients use to connect. Copy it for use later. Its Install in an AI client card has an AI client list. Select a client to get a ready-to-paste connection snippet for common MCP clients such as Claude Code, Claude, and Cursor. Each snippet already includes this server’s URL. The tab also has 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 server’s tool list depends on the signed-in user, connect your account from the banner on the detail page first. If the list is empty or shows an error, see Troubleshooting.

To mask, drop, or filter the data this server’s tools return before an agent sees it, open the Data Policies tab. See Shape Tool Data with Data Policies.

Data policies are a preview capability.

Create from the CLI

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

# Managed type with user-delegated OAuth inside the managed config
# (NetSuite example)
rpk ai mcp-server create netsuite \
  --enabled \
  --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-server create github-proxy \
  --enabled \
  --remote.url https://mcp.example.com/sse \
  --remote.transport sse \
  --remote.user-oauth.provider-name github \
  --remote.user-oauth.required-scopes repo,read:org

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

The server name is a positional argument, not a flag. Flags are grouped by backend, and the group you use selects the backend: --managed.* for a managed type, --remote.* for a self-managed server. Setting flags from both groups is an error.

A new server is disabled unless you pass --enabled. A disabled server isn’t discoverable, and listing its tools fails with server "<name>" is disabled. Pass --enabled on create, or run rpk ai mcp-server update <name> --enabled later.

For every flag, see rpk ai mcp-server create. A few flags carry behavior the reference page doesn’t spell out:

  • --remote.user-oauth.provider-name attaches a provider already registered on the Outbound providers tab of Integrations setup. It doesn’t request automatic setup. Leave it empty to set OAuth up automatically from the server URL. The principal needs dataplane_aigateway_oauthprovider_attach on the named provider. Managed servers that support user-delegated OAuth carry their authentication shape inside --managed.config. See Configure an OAuth Provider.

  • --remote.user-oauth.required-scopes sets the minimum scopes a user’s connection must have. Provide every scope any tool may need, because users must re-consent if the scopes change later.

  • --remote.user-oauth.client-id is for the automatic-setup path only, and only when the remote server supports neither client metadata documents nor dynamic client registration. A client ID you enter takes precedence over both mechanisms. Leave it empty otherwise, and when you attach a provider by name. Add --remote.user-oauth.client-secret-ref only for a confidential app.

  • --remote.user-oauth.automatic-setup matters on update. It asks Redpanda to set OAuth up automatically from the server URL instead of keeping the provider the server already has. Pass it without a provider name, because setting both is rejected. On create it’s unnecessary, because omitting the provider name already requests automatic setup.

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

List and filter servers

The MCP servers list has a search box that matches server names, and Type and Status filters.

To filter on more than that, use rpk ai mcp-server list. It accepts these flags:

  • --name-contains: Case-insensitive substring match on the server name.

  • --filter: An AIP-160 expression (maximum 1024 characters) that’s combined with --name-contains. Filterable fields are name, type, enabled, description, created_at, and updated_at. The type field accepts MCP_SERVER_TYPE_REMOTE and MCP_SERVER_TYPE_MANAGED, and enabled accepts true or false. Use OR to match more than one value, for example type = "MCP_SERVER_TYPE_REMOTE" OR type = "MCP_SERVER_TYPE_MANAGED".

  • --order-by: A comma-separated list of name or created_at, each optionally followed by ` desc`. The default is created_at desc.

  • --page-size and --page-token: Page through a long list. The command prints the token for the next page. Keep --order-by the same on every page.

You can also filter on tags. The expression tags.env = "prod" matches a tag value, and tags:env tests that a key exists. Quote a key that contains dots or slashes, for example tags."redpanda.com/agent-self" = "agents/market-bot". A server with no tags never matches a tag filter.

This example lists only managed servers, newest first, 50 at a time:

rpk ai mcp-server list \
  --filter 'type = "MCP_SERVER_TYPE_MANAGED"' \
  --order-by 'created_at desc' \
  --page-size 50

Edit, disable, and delete a server

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

  • Disable: Click Disable in the detail page header, or turn off the Enabled toggle when you edit the server. The server stays in the list, but every request returns MCP server "<name>" is disabled until you re-enable it, including a client’s attempt to connect.

  • Delete: On the Overview tab, click Delete in the Delete this MCP server section and type delete to confirm. Deleting permanently removes the server record. Detach the server from every agent first, and remove it from any Code MCP server that lists it. AI Gateway refuses to delete a server that is still in use and names what uses it. 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 an OAuth provider you attached, users don’t re-consent unless the new server requires additional scopes. A provider that AI Gateway set up automatically for a remote server is deleted with the last server that uses it.

Troubleshooting

Symptom What to check

Secret <NAME> not found

The secret reference is case-sensitive and must be UPPER_SNAKE_CASE matching the pattern ^[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 or service-account OAuth on a server with an http:// URL. Switch to https://. For user-delegated OAuth only, a cluster-local URL is also accepted where cluster-local addressing has been enabled for your environment. See Register a self-managed server.

Inspector / tools list empty after create

The connection or authentication might be failing. The Overview tab and the Inspector tools list show the discovery error. For self-managed, confirm the transport (SSE vs. Streamable HTTP) matches what your server actually speaks.

Tool calls or connections fail with MCP server "<name>" is disabled

A disabled server rejects every request, connection attempts included. Confirm the Enabled toggle is on.

Next steps