OpenAPI to MCP: Turn REST APIs into Secure AI Tools

Key Takeaways

• OpenAPI to MCP lets teams make existing REST APIs available to AI agents without building and operating a separate MCP server for every service.
• AISIX AI Gateway generates namespaced MCP tools from OpenAPI 3.x operations and presents them through the same MCP endpoint as tools from upstream MCP servers.
• The gateway keeps the caller credential separate from the credential used for the upstream REST API, so agents never receive backend secrets.
• Generated tools can use the same access controls, rate limits, guardrails, and observability pipeline as other MCP tools in AISIX.
• The conversion has deliberate boundaries: it supports common HTTP operations and JSON request bodies, but does not turn Swagger 2.0 or multipart uploads into tools.
• A production rollout should expose a small, reviewed set of operations first, grant exact tool names, and verify both permitted and denied calls.

OpenAPI to MCP is most valuable when an enterprise does not begin its AI-agent journey with a blank infrastructure diagram. Most organizations already have years of business capability behind REST APIs: inventory lookups, support tickets, payment status, deployment operations, employee directories, and internal search. The fastest route to useful agents is often not to rebuild those systems. It is to give agents a safe, machine-readable way to use them.

The Model Context Protocol (MCP) provides that interface. An MCP client can discover tools, inspect their input schemas, and invoke them through a standard protocol. The difficult part is turning a large API estate into that tool surface without creating another application for every API, copying credentials into agent runtimes, or bypassing existing operational controls.

AISIX AI Gateway addresses that problem by accepting an OpenAPI 3.x document as an MCP server source. It generates tools from supported API operations, executes tool calls as HTTP requests, and keeps authentication, authorization, traffic control, content inspection, and telemetry in the gateway path.

Why Rebuilding Every API as an MCP Server Does Not Scale

A purpose-built MCP server can be the right choice when it adds orchestration, state, or domain logic that does not exist in a backend API. But creating a new MCP server only to wrap an already well-described REST endpoint produces a second integration surface that teams must develop, secure, deploy, version, and monitor.

Imagine that an organization wants an operations agent to use three existing services:

• an inventory API that looks up stock by SKU;
• a ticketing API that creates and reads incidents;
• a deployment API that reports release status.

The agent needs tool names, descriptions, and input schemas. It does not need three new business implementations. OpenAPI already describes the operations, parameters, and JSON request bodies. An OpenAPI-to-MCP layer can translate those contracts into tools while leaving the underlying APIs unchanged.

flowchart LR
    Specs["OpenAPI 3.x documents"] --> Gateway["AISIX AI Gateway"]
    Servers["Upstream MCP servers"] --> Gateway
    Gateway --> Endpoint["Aggregated /mcp endpoint"]
    Endpoint --> Agent["MCP client or AI agent"]
    Gateway --> Inventory["Inventory REST API"]
    Gateway --> Tickets["Ticketing REST API"]
    Gateway --> Deployments["Deployment REST API"]

This separation creates a cleaner ownership model. API teams continue to own business behavior and the OpenAPI contract. Platform teams own the gateway, credentials, and policy. Agent teams consume a stable MCP tool surface instead of writing protocol adapters and secret-handling logic into every application.

It also reduces governance drift. A generated tool does not create a direct route around the gateway. Calls remain subject to the controls that platform and security teams apply to MCP traffic.

How AISIX Converts OpenAPI to MCP Tools

In AISIX, an MCP server registry entry can use type: openapi and point to a REST API base URL. Its OpenAPI 3.x document supplies the tool definitions. AISIX walks the document's paths and generates one tool for each supported get, post, put, delete, or patch operation.

Tool naming is deterministic. When an operation has an operationId, AISIX lowercases it, replaces unsupported characters, and caps the result at 128 characters. Without an operationId, the gateway derives a name from the HTTP method and path. The registered server name is then added as a namespace. An operation called getItem on a server named erp is exposed through the aggregated endpoint as erp__getitem.

Consider this minimal OpenAPI document:

openapi: 3.0.3
info:
  title: ERP Inventory API
  version: 1.0.0
paths:
  /items/{id}:
    get:
      operationId: getItem
      summary: Get an inventory item by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Inventory item found

AISIX turns the path parameter into a required tool input and exposes the operation as erp__getitem. Path and query parameters retain useful schema information such as type, description, enum values, and required state. A JSON request body becomes a body object. Local $ref values are resolved so the MCP client receives the actual referenced schema instead of an unresolved pointer.

The conversion intentionally excludes fields that should remain under gateway control. Header and cookie parameters are not exposed as agent-supplied tool arguments. They often carry credentials, tenant routing, or other infrastructure context that should be set by trusted policy rather than generated by a model.

There are also practical limits to the conversion:

• The document must be OpenAPI 3.x; Swagger 2.0 is rejected.
• An operation with no application/json request-body variant is skipped. A multipart file upload, for example, is not generated as a tool.
• AISIX Cloud rejects documents that cannot be parsed, have no usable operations, or contain operationId values that collide after normalization.
• With the open-source resources file, validation checks the resource shape, while the gateway generates tools when clients list or invoke them. Name collisions receive numeric suffixes, so teams should inspect the resulting tool list before release.

These limits are useful design signals. An API being technically reachable does not automatically make every operation a good agent tool. File uploads, unusually encoded bodies, and broad administrative endpoints often deserve purpose-built workflows rather than automatic exposure.

Use direct conversion when one API operation already represents one clear business action. Build a purpose-specific MCP server when a tool must coordinate several APIs, preserve session state, pause for human approval, or reshape unstable backend responses into a durable contract. That boundary keeps protocol reuse from becoming accidental workflow design.

Treat the OpenAPI document as a governed release artifact, not a live discovery shortcut. In AISIX Cloud, spec_url is fetched and stored during registration; the data plane does not repeatedly fetch it, so an external document change does not silently alter the tool catalog. Use spec_content when the control plane cannot reach a private specification, and remember that Cloud documents are capped at 1 MiB. In an open-source deployment, changes enter through the reviewed resources.yaml reload. In either path, version the document, compare generated tool names before release, and update caller grants only after the new surface is understood.

Keep API Credentials and Destinations Under Gateway Control

OpenAPI conversion solves only the interface problem. A production design must also establish who can call the generated tool and how the gateway authenticates to the backend API. Those are separate trust boundaries.

The MCP client sends an AISIX caller API key to the gateway. AISIX uses that key to authenticate the caller and calculate its effective tool grant. The gateway then uses the credential configured on the OpenAPI-backed server when it calls the REST API. The caller key is never forwarded as the upstream credential, and the backend credential is never returned to the client.

AISIX supports four upstream modes:

• none for a service that requires no gateway credential;
• bearer for a static bearer token;
• api_key for a key sent in x-api-key, or a custom header selected with api_key_header for an OpenAPI-backed server;
• oauth2 for the client credentials flow, with access-token caching.

This gives the platform team one place to rotate or revoke backend credentials without changing agent configuration. A failure on one upstream credential makes that server's tools unavailable, but does not expose the secret or prevent unrelated MCP servers from operating.

AISIX also applies destination protections when it executes generated tools. It does not follow redirects, preventing a credential from being resent to an unexpected host. For path parameters, it rejects values containing / or \, as well as . and .., so a caller cannot use a generated path field to escape the configured operation path.

The resulting request flow keeps both identity and credentials explicit:

sequenceDiagram
    participant Client as MCP Client
    participant AISIX as AISIX AI Gateway
    participant Policy as Access and Safety Controls
    participant API as REST API

    Client->>AISIX: tools/call erp__getitem + caller API key
    AISIX->>Policy: Authorize tool and check limits
    Policy-->>AISIX: Allow
    AISIX->>Policy: Inspect tool arguments
    Policy-->>AISIX: Pass
    AISIX->>API: GET /items/42 + gateway-held credential
    API-->>AISIX: JSON response
    AISIX->>Policy: Inspect text result
    Policy-->>AISIX: Pass
    AISIX-->>Client: MCP tool result

The design does not assume that an agent is trustworthy because it has a valid key. It authenticates the caller, authorizes the specific tool, constrains traffic, and inspects content before and after the backend call.

From Generated Tool to Production-Ready Tool

AISIX Cloud can register an OpenAPI-backed server through the Admin API. The following example keeps secrets in environment variables and exposes an ERP API to one environment:

export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export ERP_API_TOKEN="YOUR_ERP_SERVICE_TOKEN"

curl -fsS -X POST "$AISIX_CP/mcp_servers" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "name": "erp",
  "type": "openapi",
  "url": "https://erp.internal/api/v1",
  "spec_content": "{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"ERP\",\"version\":\"1.0.0\"},\"paths\":{\"/items/{id}\":{\"get\":{\"operationId\":\"getItem\",\"parameters\":[{\"name\":\"id\",\"in\":\"path\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"description\":\"OK\"}}}}}}",
  "auth_type": "bearer",
  "secret": "$ERP_API_TOKEN",
  "allowed_environments": ["$ENV_ID"]
}
EOF

After registration, review tool_names in the response or use the server's tools endpoint. Then grant the narrowest practical name, such as erp__getitem, to the caller. Avoid granting erp__* when an agent needs only one read operation.

The open-source AISIX gateway uses the same runtime behavior through resources.yaml:

_format_version: "1"

api_keys:
  - display_name: inventory-agent
    key_env: INVENTORY_AGENT_KEY
    allowed_models: []
    allowed_tools:
      - erp__getitem

mcp_servers:
  - name: erp
    type: openapi
    url: https://erp.internal/api/v1
    auth_type: bearer
    secret: ${ERP_API_TOKEN}
    spec:
      openapi: 3.0.3
      info:
        title: ERP Inventory API
        version: 1.0.0
      paths:
        /items/{id}:
          get:
            operationId: getItem
            parameters:
              - name: id
                in: path
                required: true
                schema:
                  type: string
            responses:
              "200":
                description: Inventory item found

Validate the complete resources file before reloading the gateway. Then test three behaviors: the permitted tool appears in tools/list, the permitted call reaches the ERP API, and a different generated tool is hidden and rejected before upstream routing.

Generation should be the beginning of the production workflow, not the end. In AISIX Cloud, teams can require review and approval before publishing the server, then use shared MCP access policies for environment and team access. Both Cloud and open-source deployments can apply per-key tool grants, request and concurrency limits, guardrails, and telemetry. Budgets, shared policies, and the server review workflow are AISIX Cloud capabilities.

OpenAPI to MCP FAQ

Can AISIX convert any API into MCP tools?

AISIX generates tools from supported operations in an OpenAPI 3.x document. The source must be a REST API described by OpenAPI; operations with unsupported request-body formats are not converted automatically. Review the generated tool list instead of assuming that every path became callable.

Does the MCP client receive the REST API credential?

No. The client authenticates to AISIX with a caller API key. AISIX separately attaches the configured bearer token, API key, or OAuth2 client-credentials token to the upstream request. The backend credential stays gateway-side.

Does OpenAPI to MCP support Swagger 2.0 or multipart uploads?

Swagger 2.0 documents are not accepted by this AISIX workflow. An operation without an application/json request-body variant, including a multipart file upload, is skipped rather than exposed as a tool that cannot be executed correctly.

Make Existing APIs Useful to Agents Without Losing Control

OpenAPI to MCP is valuable because it reuses two assets enterprises already trust: the REST API implementation and its machine-readable contract. AISIX adds the missing protocol and governance layer. Agents receive tools with predictable names and schemas, while platform teams retain control of credentials, authorization, traffic, content inspection, and telemetry.

Start with one read-only API and one exact tool grant. Verify the generated schema, test allowed and denied calls, and observe the resulting usage event. Once that path is proven, add least-privilege MCP access control before expanding the tool catalog.

See the complete Expose a REST API as MCP Tools guide to register an OpenAPI document and call your first generated tool through AISIX AI Gateway.