# OpenAPI Managed 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: OpenAPI Managed MCP Server page-beta-text: This is a beta feature. Beta features are available for testing and feedback. They are not supported by Redpanda and should not be used in production environments. 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: managed/openapi page-component-name: agentic-data-plane page-version: master page-component-version: master page-component-title: Agentic Data Plane page-relative-src-path: managed/openapi.adoc page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/connect/pages/managed/openapi.adoc # Beta release status page-beta: "true" description: Expose any OpenAPI 3.x-described HTTP API as MCP tools. Point Redpanda at a spec URL and get a fully-typed tool surface for agents, with no custom code. page-topic-type: how-to personas: agent_builder, platform_engineer learning-objective-1: Configure the OpenAPI managed MCP server against an OpenAPI 3 spec learning-objective-2: Pick the right authentication mode for the upstream API learning-objective-3: Verify generated tools through the Inspector page-git-created-date: "2026-05-28" page-git-modified-date: "2026-06-11" release-status: beta - This is a beta feature. Beta features are available for testing and feedback. They are not supported by Redpanda and should not be used in production environments. --- The **OpenAPI** managed MCP server is the "bring your own API" escape hatch. Hand it an OpenAPI 3.x spec, and it generates one MCP tool per operation in the spec. No custom code, no per-API managed type: useful when the API you want to expose is not in the catalog. After reading this page, you will be able to: - Configure the OpenAPI managed MCP server against an OpenAPI 3 spec - Pick the right authentication mode for the upstream API - Verify generated tools through the Inspector ## [](#what-this-mcp-server-does)What this MCP server does The OpenAPI managed type: - Loads an OpenAPI 3.x spec (3.0 or 3.1) from a URL or pasted JSON/YAML. Swagger 2.0 specs are not supported. - Generates one MCP tool per operation, with input schemas derived from the spec’s parameter and request-body schemas. `oneOf`, `anyOf`, and `discriminator` are supported; `callbacks` are not. - Forwards calls to the upstream API, applying the configured authentication. By default the generator walks schemas up to a depth of 5 (`max_schema_depth`); schemas nested deeper than that are truncated. ## [](#prerequisites)Prerequisites - An HTTP API with an OpenAPI 3.x spec. - The spec URL or the spec content itself. - Credentials for the API, if it requires them. ## [](#configure)Configure 1. Open **MCP Servers > Create Server**. 2. Pick **OpenAPI** from the marketplace picker. 3. Fill in identity fields (`name`, `description`). 4. In the OpenAPI configuration form: - `Spec`: A URL to the OpenAPI 3.x spec (JSON or YAML), or paste the spec inline. Set exactly one. Inline specs are capped at 3 MiB; host larger specs and use the URL instead. - `Base URL override` (optional): Useful when the spec’s `servers` block doesn’t match your environment. - `Operation filter` (optional): Include or exclude operations by tag, `operationId` glob, path glob, or HTTP method. - `Max schema depth` (optional): Maximum depth for schema conversion. Defaults to 5. - `Extract headers` (optional): Response header names to surface to the agent, such as `X-CSRF-Token` or `Set-Cookie`. Listed headers are appended to the tool result; all other response headers are dropped. Matching is case-insensitive. 5. Configure authentication (see [Authentication](#authentication)). 6. Click **Create**. ## [](#authentication)Authentication OpenAPI is the most flexible managed type for authentication: the upstream API can need anything. All the standard authentication modes apply: | Mode | Use when | | --- | --- | | None | Public APIs (rare in practice). | | Bearer | API expects a bearer token. The handler sends Authorization: Bearer . | | API key | API expects a key in a header or query parameter. Choose the placement and the parameter name. | | Basic | API expects HTTP Basic authentication (a username and password). | | User-delegated OAuth | API supports OAuth on behalf of users and you want per-user identities. Requires an OAuth Provider configured for that API. See Configure User-Delegated OAuth. | ## [](#test)Test 1. Open the **Inspector** tab. 2. The Tools panel lists every operation from your spec, named per the `operationId` (or per the path if `operationId` is missing). Tool names longer than 64 characters are truncated and given a short hash suffix to keep them unique, because LLM providers cap tool-name length. Parameter names that start with `$` (common in OData APIs, such as `$top` and `$filter`) appear without the `$` prefix in the tool schema; the server still sends the original parameter name to the API. 3. Pick one and run it. The Inspector renders a form from the operation’s parameter and request-body schemas. See [Test an MCP Server’s Tools with the Inspector](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/) for general Inspector usage. ## [](#use-with-agents)Use with agents Once tools generate cleanly, point an agent at the **API URL** on the server’s detail page. The agent sees one tool per OpenAPI operation, named accordingly. Every generated tool also accepts an optional `headers` input, which lets the agent set request headers the spec doesn’t declare. Agent-supplied headers can’t override the configured authentication headers or the spec’s own header parameters. Combined with `Extract headers`, this supports APIs that round-trip headers, such as a CSRF token fetched from one response and echoed on the next request. ## [](#troubleshooting)Troubleshooting | Symptom | What to check | | --- | --- | | "Failed to load spec" | Confirm the spec URL is reachable from Redpanda ADP and serves valid JSON or YAML. CORS doesn’t matter (Redpanda fetches server-side). | | Tools list doesn’t include an expected operation | The operation may be missing an operationId, or the operation include/exclude filters might be excluding it. If two operations resolve to the same tool name, the server keeps one, drops the other, and logs a warning naming both. | | Tool input schema looks wrong | oneOf, anyOf, and discriminator are supported, but callbacks are not, and schemas deeper than max_schema_depth (default 5) are truncated. Adjust the spec or raise the depth. | | Calls return 401 | Authentication mode or credentials are wrong. Confirm secret content and the API’s expected authentication header. | | Calls return 404 with the right operation | servers block in the spec doesn’t match your real API endpoint. Use the Base URL override. | ## [](#limitations)Limitations - **Custom tool logic**: The OpenAPI type is purely a spec-to-tools generator. For business logic on top of the API, use a [self-managed MCP server](https://docs.redpanda.com/agentic-data-plane/connect/register-remote/). - **GraphQL APIs**: OpenAPI doesn’t describe GraphQL. For GraphQL APIs, use a self-managed server. - **gRPC services**: Same as GraphQL: use a self-managed server.