Register a Self-Managed MCP Server
Register your existing MCP server with Redpanda to add authentication and observability 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 Agentic Data Plane
-
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 Redpanda-managed URL for each server, with Inspector, observability, and agent access, without standing up your own gateway.
If you don’t already run a server, use a managed type. See Managed catalog.
Prerequisites
-
An MCP server reachable from the AI Gateway. The AI Gateway doesn’t connect to loopback, cloud metadata, link-local, multicast, IPv6 unique local, or unspecified addresses, or to your environment’s own VPC, pod, and service address ranges, except cluster-local services your environment has been enabled to reach.
-
The endpoint URL.
http://is allowed except with user-delegated OAuth and service-account OAuth, which requirehttps://. User-delegated OAuth has one exception, for cluster-local servers (see Troubleshooting). -
Knowledge of which transport the server speaks (SSE or Streamable HTTP). If you don’t know, see Transport choice.
-
If the server’s certificate comes from a private certificate authority (CA), or the server signs it itself: the CA certificate, or the server’s own self-signed certificate, in PEM form. See Trusted certificates.
-
If using static-key or service-account OAuth: secrets pre-created in the Redpanda Agentic Data Plane secret store,
UPPER_SNAKE_CASE. -
If using user-delegated OAuth with automatic setup: nothing, when the server accepts a client metadata document or supports dynamic client registration. If it supports neither, register an OAuth app with the upstream vendor and have its client ID ready, plus a client-secret reference in the secret store for a confidential app.
-
If attaching an OAuth provider your organization already manages instead: the provider registered first. See User-delegated OAuth.
Create the server
-
Open MCP servers in the sidebar and click Add MCP server.
-
In the marketplace picker, click Remote (Proxied).
-
In the Identity section, replace the suggested
Nameand optionally add aDescription. The constraints are the same as in Create an MCP Server. -
In the Connection section, enter Server URL and pick Transport. If the server’s certificate doesn’t chain to a public CA, add the CA certificate, or the server’s own certificate, to Trusted certificates. See Trusted certificates.
-
Configure authentication (see Authentication).
-
Click Create server.
Transport choice
Two transports are available:
-
Streamable HTTP: The current MCP transport, recommended for new servers.
-
SSE: Server-sent events. The older MCP transport, still widely deployed.
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 (JSON or an SSE stream) on success.
curl -X POST -H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}' \
https://your-server.example.com/mcp
Trusted certificates
The AI Gateway verifies your server’s TLS certificate against the public CAs in its own trust store. A certificate that comes from a private CA, or that the server signs itself, chains to none of them. Every call to the server then fails until you tell the gateway to trust that certificate.
The optional Trusted certificates field appears on both the create and the edit form, with the server URL and the transport. It takes PEM CERTIFICATE blocks. List the CA certificate that signs your server’s certificate, or the server’s own self-signed certificate.
Select Upload file to choose a .pem, .crt, or .cer file or drag one in, or select Paste to paste the blocks in. A loaded file replaces whatever the field holds, and the form reports how many certificates it read. Agentic Data Plane refuses a file that holds no PEM certificate. On a server that already has certificates, those certificates stay until you choose a file.
The gateway trusts these certificates on top of its own trust store, and only for this server. No other MCP server, LLM provider, or OAuth provider trusts them. They cover the calls the gateway proxies to the server and its tool discovery. With service-account OAuth, they also cover the token request to the server’s token URL.
Agentic Data Plane refuses to save text that holds anything other than PEM CERTIFICATE blocks. It also refuses a certificate that has already expired. It rejects text that contains a private key, because it stores and returns this field as plain text.
When the gateway can’t verify the certificate, the server’s Overview tab and the Inspector tools list report the certificate error that tool discovery returned. A tool call an agent makes through the server’s proxy URL fails with a more general message that the gateway couldn’t reach the server.
After a stored certificate expires, the gateway no longer verifies a chain that needs it, and calls to the server fail. You can still edit, disable, and re-enable the server, because Agentic Data Plane checks the field only when you change it. If the list holds another certificate that the server’s chain can use, calls keep working.
Authentication
The authentication modes from Create an MCP Server 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- |
Service-account OAuth |
The upstream system supports OAuth client credentials and you want one shared identity for all callers. The server URL must use |
Token passthrough |
The upstream server already validates client tokens. Redpanda forwards the caller’s |
For user-delegated OAuth, the URL must be https://, unless it addresses a server inside your own cluster and cluster-local addressing has been enabled for your environment. Redpanda can set up OAuth automatically for the server, or you can attach an OAuth provider you already registered. See User-delegated OAuth.
If the server sits behind Google Identity-Aware Proxy or a Cloud Run service that requires authentication, AI Gateway can send a Google ID token in addition to the server’s own authentication. See Connect to an MCP Server Behind Google Identity-Aware Proxy.
Tool discovery
After create, Redpanda runs a live tools/list against the server and shows the result 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, open the Inspector tab, click Session details, and then click Refresh to re-run discovery against the server.
Connection errors and retry
| Error | What it means |
|---|---|
|
The user-delegated authentication path has no stored connection for the calling user. The failed tool result carries the authorization URL so the user can complete the consent flow, then call the tool again. See User-delegated OAuth. |
|
The user’s stored token has expired and refresh failed. Have the user reconnect. |
Plain connection error / 502 / 504 |
Redpanda couldn’t reach your server. The Overview tab and the Inspector tools list show the upstream error. |
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 |
TLS errors when registering an |
Confirm the server’s certificate chains to a public CA. If it chains to a private CA, or the server signs it itself, add the CA certificate, or the server’s own certificate, to Trusted certificates. See Trusted certificates. |
|
Authentication is misconfigured. For static-key or service-account OAuth, verify the secret content and the |
Tool schema parse errors |
The server returned a |
The URL is refused for targeting a cluster-local host |
A URL whose host ends in |