Agentic Data Plane
beta

OpenAPI Managed MCP Server

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

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

  • 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

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

  6. Click Create.

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

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

  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 for general Inspector usage.

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

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

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

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