Agentic Data Plane

OpenAPI Managed MCP Server

The OpenAPI managed MCP server is the "bring your own API" escape hatch. Hand it an OpenAPI 3.0 spec, and it generates one MCP tool per operation in the spec. It needs no custom code and no per-API managed type, which makes it 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.0 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.0 spec 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. allOf, oneOf, and anyOf are flattened into a single object schema; discriminator is ignored and callbacks are not supported.

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

For a complete walkthrough against a real API, see Set Up Snowflake as an OpenAPI MCP Server.

Prerequisites

  • An HTTP API with an OpenAPI 3.0 spec.

  • The spec URL or the spec content itself.

  • Credentials for the API, if it requires them.

Configure

  1. Open MCP servers in the sidebar.

  2. Click Add MCP server.

  3. Click the OpenAPI card in the marketplace picker.

  4. Replace the suggested Name, and optionally add a Description.

  5. Optionally, turn off Enable code mode. It’s on by default in the create form for OpenAPI servers. rpk ai mcp-server create leaves it off unless you pass --code-mode. See Code Mode.

  6. In the OpenAPI configuration form:

    • Spec: A URL to the OpenAPI 3.0 spec (JSON or YAML).

    • Spec Content: The spec itself, pasted or loaded from a file, when you don’t host it. Set exactly one of Spec and Spec Content. Inline specs are capped at 3 MiB; host larger specs and use the URL instead.

    • Base URL (optional): Useful when the spec’s servers block doesn’t match your environment.

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

  7. Configure authentication (see Authentication).

  8. Click Create server.

Authentication

OpenAPI is the most flexible managed type for authentication, because the upstream API can need anything. All the standard authentication modes apply:

Mode Use when

No Auth

Public APIs (rare in practice).

Bearer

API expects a bearer token. The server 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 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.

Service Account OAuth

API supports the OAuth client-credentials grant and you want a single shared service-account identity for every call, rather than per-user tokens.

For Service Account OAuth, the gateway runs the client-credentials exchange once per server and shares the resulting token across all callers. Supply the client ID, a secret-store reference for the client secret, the token URL, and any scopes the API requires. Store the client secret in the Agentic Data Plane secret store under an UPPER_SNAKE_CASE key, such as OAUTH_CLIENT_SECRET, and reference it from the form. Use an https token endpoint.

Test

  1. Open the Inspector tab.

  2. The Tools panel lists every operation from your spec. Each tool is named from the operation’s operationId, lowercased, with characters other than letters and digits replaced by underscores. For example, getPetById becomes getpetbyid. An operation without an operationId is named from its method and path, for example get_pets_by_id for GET /pets/{id}. 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. Click a tool 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

After tools generate cleanly, point an agent at the Server URL on the server’s Connection tab. The agent sees one tool per OpenAPI operation, named accordingly.

To attach the server to a managed agent, add it in the agent’s Tools section. See Tools.

Each tool returns the upstream response as a structured result with the fields status_code, headers, and body. body is the parsed JSON payload when the response is JSON, or the raw response text otherwise. headers holds the response headers you selected with Extract Headers, and is empty when none are configured. Agents that read structured output can address these fields directly, and a plain-text copy of the same result is also included for clients that read only text. A 4xx or 5xx response surfaces as a tool error rather than a structured result.

Every generated tool also accepts an optional extra_headers input: an array of objects, each with a key (the header name) and a value. It lets the agent set request headers the spec doesn’t declare, for example "extra_headers": [{"key": "X-CSRF-Token", "value": "abc"}]. 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 Agentic Data Plane and serves valid JSON or YAML. CORS doesn’t matter (Redpanda fetches server-side).

Tools list doesn’t include an expected operation

The operation include or exclude filters might be excluding it. When you set an include filter on operationId, operations that have no operationId are excluded. 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

allOf, oneOf, and anyOf are handled by flattening: for oneOf and anyOf, all member properties are merged into a single object and every property becomes optional, so the schema doesn’t enforce which variant you pick. An OpenAPI discriminator is ignored, callbacks are not supported, 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 field.

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: As with GraphQL, use a self-managed server.

Next steps