Agentic Data Plane

Register a Self-Managed MCP Server

Register your existing MCP server with Redpanda to add authentication, observability, and agent aggregation without changing your server’s code. This guide covers the self-managed path from Create an MCP Server in depth. Choose this when you already run a server and want Redpanda to proxy it.

After completing this guide, you will be able to:

  • Register a self-managed MCP server in ADP

  • Pick the right transport (SSE vs. Streamable HTTP) and authentication mode

  • Confirm tool discovery completed and the server is reachable through its proxy URL

When to use this

Choose self-managed registration when:

  • The MCP server is already deployed in your environment and you don’t want to migrate it to a managed type.

  • You need custom tool logic that no managed type provides.

  • You want a unified MCP URL (and Inspector / observability / agent access) across servers without standing up your own gateway.

If you don’t already run a server, prefer a managed type. See Managed catalog for the catalog.

Prerequisites

  • An MCP server reachable from the Agentic Data Plane.

  • The endpoint URL. http:// is allowed for everything except user-delegated OAuth, which requires https:// (proto rule remote_mcp.user_oauth_requires_https).

  • Knowledge of which transport the server speaks (SSE or Streamable HTTP). If you don’t know, see Transport choice.

  • If using static-key or service-account-OAuth: secrets pre-created in the Redpanda ADP secret store, UPPER_SNAKE_CASE (proto regex ^[A-Z][A-Z0-9_]*$).

  • If using user-delegated OAuth: an OAuth Provider already configured. See User-delegated OAuth.

Create the server

  1. Open MCP Servers in the sidebar and click Create Server.

  2. In the marketplace picker, choose Remote (Proxied).

  3. Fill in the identity fields (name, description, enabled); same constraints as in Create an MCP Server.

  4. Provide the URL and Transport.

  5. Configure authentication (see Authentication).

  6. Click Create.

Transport choice

Two transports are available on the proto enum MCPTransport:

  • SSE: Server-sent events. The traditional MCP transport.

  • Streamable HTTP: Newer bidirectional protocol.

Pick whichever your server actually speaks. To probe a server quickly:

# SSE handshake: expect a stream of `event:` lines on success.
curl -N -H "Accept: text/event-stream" https://your-server.example.com/mcp/sse

# Streamable HTTP: expect a JSON-RPC response on success.
curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  https://your-server.example.com/mcp

Authentication

The authentication modes from create-server.adoc all apply. Several patterns are particularly common for self-managed servers:

Pattern Use when

Static key with a custom header

First-party servers that authenticate with a non-Authorization header. Provide a header_name (for example, X-Api-Key) and a key_ref pointing at a UPPER_SNAKE_CASE secret.

Service-account OAuth

The upstream system supports OAuth client credentials and you want one shared identity for all callers. Provide client_id, client_secret_ref, token_url, and any required scopes.

Token passthrough

The upstream server already validates client tokens; Redpanda just forwards the caller’s Authorization header.

For user-delegated OAuth, the URL must be https:// and you also need an OAuth Provider. See User-delegated OAuth.

Tool discovery

After create, Redpanda runs a live tools/list (the ListMCPServerTools RPC) against the server. The result is cached on the MCPServer.tools output-only field and shown on the detail page’s Overview tab. The Inspector tab (see Test a server’s tools) exercises individual tools.

If the tools list is empty or stale, hit the Refresh tools action on the Overview tab to re-query the server.

Connection errors and retry

Error What it means

OAuthConnectionRequired

The user-delegated auth path needs a stored token vault entry for the calling user. Redpanda surfaces an authorize_url so the user can complete the consent flow. See User-delegated OAuth.

OAuthTokenExpired

The user’s stored token has expired and refresh failed. Surface the new authorize URL and have the user re-consent.

Plain connection error / 502 / 504

Redpanda couldn’t reach your server. Look at the Connection tab on the detail page for the upstream error and check the connection-status banner.

Troubleshooting

Symptom What to check

"Transport mismatch" or empty stream

Your server speaks the other transport. Re-probe with curl per Transport choice and update the Transport field on the server’s edit page.

TLS errors when registering an https:// URL

Confirm the server’s certificate chains to a public CA (or the CA Redpanda’s egress trusts). Self-signed certs aren’t supported.

401 Unauthorized from the upstream

Authentication is misconfigured. For static-key or service-account-OAuth, verify the secret content and header_name. For token passthrough, confirm the caller is sending an Authorization header.

Tool schema parse errors

The server returned a tools/list response with an invalid JSON schema for one or more tool inputs. Fix the upstream tool’s schema and refresh.

Next steps