# 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.1.5
latest-console-tag: v3.7.4
latest-connect-version: 4.96.1
latest-redpanda-tag: v26.1.10
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 ADP
learning-objective-2: Configure each authentication mode and pick the right one for your use case
learning-objective-3: Save the server, verify the API URL, and confirm tools were discovered
page-git-created-date: "2026-05-28"
page-git-modified-date: "2026-06-10"
---

<!-- 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 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)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](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/).


## [](#open-the-mcp-servers-page)Open the MCP Servers page

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

2.  Click **Create 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]$); 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, 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-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. 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. |

> 📝 **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 **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.

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

## [](#save-and-verify)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](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).

## [](#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 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, 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 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)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/)

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