# Create an MCP Server

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt)

---
title: Create an MCP Server
latest-operator-version: v26.2.1
latest-console-tag: v3.10.0
latest-connect-version: 4.104.0
latest-redpanda-tag: v26.2.1
docname: create-server
page-component-name: agentic-data-plane
page-version: master
page-component-version: master
page-component-title: Agentic Data Plane
page-relative-src-path: create-server.adoc
page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/create-server.adoc
description: Create an MCP server in the Agentic Data Plane by picking a managed type from the marketplace or registering a self-managed server you host yourself, then configure authentication, code mode, and access.
page-topic-type: how-to
personas: agent_builder, platform_engineer
learning-objective-1: Create a managed or self-managed MCP server in Agentic Data Plane
learning-objective-2: Configure each authentication mode and pick the right one for your use case
learning-objective-3: Save the server, verify the server URL, and confirm tools were discovered
page-git-created-date: "2026-05-28"
page-git-modified-date: "2026-08-03"
---

<!-- Source: https://docs.redpanda.com/agentic-data-plane/connect/create-server.md -->

Create MCP servers to give agents structured access to your databases, queues, CRMs, and other business systems. Each server exposes [tools](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#tool), [resources](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#resource), and [prompts](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#prompt) 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)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 on a managed server, or to attach an existing provider on a self-managed server: an [OAuth provider](https://docs.redpanda.com/agentic-data-plane/reference/glossary/#oauth-provider) resource already configured. See [User-delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/).

-   For automatic OAuth setup on a self-managed server: nothing, unless the server doesn’t support dynamic client registration. In that case, 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)Open the MCP Servers page

1.  Open **MCP Servers** in the sidebar.

2.  Click **Add MCP server**.


## [](#pick-a-backend)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](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/). To go deep on the self-managed path (transport choices, TLS, multi-server aggregation), see [Register a self-managed server](https://docs.redpanda.com/agentic-data-plane/connect/register-remote/).

## [](#name-and-basic-fields)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)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](https://docs.redpanda.com/agentic-data-plane/connect/managed/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.

> 📝 **NOTE**
>
> 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-remoteproxied-only)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)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. 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 My Connections. See User-delegated OAuth for the full flow. |

> 📝 **NOTE**
>
> 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)Code mode (optional)

Toggle **Enable 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 **Connection** tab surfaces a second URL, the `Code Mode URL`, that clients can connect to instead of the standard one.

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

## [](#output-format-optional)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 gateway re-encodes a result only when it can do so without losing data. When a result isn’t tabular, or can’t be converted losslessly, 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.

> 📝 **NOTE**
>
> Output format is a preview capability.

## [](#save-and-verify)Save and verify

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

2.  Open the detail page. The **Overview** tab summarizes the server, including its discovered tools, attached agents, and server metadata.

3.  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 7 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.

4.  Open the **Connection** tab to get the `Server URL` that clients use to connect. Copy it for use later. The tab also gives you ready-to-paste connection snippets, pre-filled with this server’s 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.

5.  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](https://docs.redpanda.com/agentic-data-plane/connect/test-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](#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](https://docs.redpanda.com/agentic-data-plane/connect/data-policies/).

> 📝 **NOTE**
>
> Data policies are a preview capability.

## [](#create-from-the-cli)Create from the CLI

Use [`rpk ai`](https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/) for a non-UI path through the same create flow, useful for scripting and CI.

```bash
# Managed type (Workday example)
rpk ai mcp-server 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-server 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-server 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-server 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 on the Outbound providers tab of Integrations setup. This flag is the attach-a-provider path; it doesn’t request automatic OAuth setup. See Configure an OAuth Provider. The principal needs dataplane_aigateway_oauthprovider_attach on the named provider. 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)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](https://docs.redpanda.com/agentic-data-plane/gateway/connect-agent/#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.

```bash
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, 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)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)Next steps

-   [Configure User-Delegated OAuth](https://docs.redpanda.com/agentic-data-plane/connect/user-delegated-oauth/)

-   [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/)

-   [Shape Tool Data with Data Policies](https://docs.redpanda.com/agentic-data-plane/connect/data-policies/)

-   [Plug in an App, Database, or Tool](https://docs.redpanda.com/agentic-data-plane/connect/managed/managed-catalog/)