OpenAPI Servers

​

Overview

​

How operations become tools

​

What is not exposed

• multipart/form-data, application/octet-stream and other binary request bodies (file uploads).
• Streaming request bodies (OpenAPI 3.2 itemSchema: text/event-stream, application/jsonl, application/json-seq).
• Operations that reference schemas in other files (external $ref).
• Deprecated operations, unless include_deprecated is set.

​

Base URL

​

Authentication

1. Security schemes from the document. The preview lists every securitySchemes entry. For apiKey (header, query or cookie) and http bearer schemes you enter one value; for http basic a username and password. Values accept env.VAR and vault.path references. Stored credentials are encrypted only when encryption_key (or BIFROST_ENCRYPTION_KEY) is configured; without a key they are stored in plain text. The first security requirement of an operation whose schemes all have a credential is applied.
2. The server’s own auth type. none, headers (static headers sent with every request) and per_user_headers (each caller supplies their own values) work as for any other server. OAuth and token exchange do not apply: there is no MCP server to run that handshake against. For the same reason a caller’s per-user headers are saved once every required key has a value, with no verification handshake; the upstream API sees them on the first tool call.

​

Per-user credentials for security schemes

​

Configuration

• Web UI
• API
• config.json

1. Navigate to MCP Gateway and click Add MCP Server.
2. Under Server source, choose Generate from an OpenAPI spec (marked BETA). The connection type and connection URL fields give way to the document source.
3. Supply the document: Paste it or Upload a file and it is parsed as soon as you stop typing, or give its URL and click Fetch spec. Parse errors show under the editor, with Parse again to retry.

4. Review the preview: the document’s title and version, the Base URL, credential inputs for its security schemes, and the operations. Untick anything the server should not expose. Unsupported operations are shown disabled with the reason.

5. Set the server’s name, auth type, static headers and the other options as for any server, then click Create.

To swap the document later, open the server, and on the General tab click Replace spec. Each operation is matched by method and path, so a selected operation stays selected, and its auto-execute setting and tool price follow it, even if its tool name changes. Settings of operations the new document drops are removed. The server is rebuilt from the new document when you save.

Preview first to see the tool names the document yields:

curl -X POST http://localhost:8080/api/mcp/openapi/preview \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-session-token>" \
  -d '{
    "spec_url": "https://petstore3.swagger.io/api/v3/openapi.json"
  }'

The response lists tools (name, method, path, input schema), unsupported operations with a reason, security_schemes, servers, the resolved base_url, and echoes the fetched document as spec together with spec_url, the URL it was finally read from after redirects. Send that URL with the document on create, so relative servers resolve the way the preview showed them. Then create the server, naming the tools to expose:

curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-session-token>" \
  -d '{
    "name": "petstore",
    "connection_type": "openapi",
    "auth_type": "none",
    "tools_to_execute": ["getInventory", "getPetById"],
    "openapi_config": {
      "spec_url": "https://petstore3.swagger.io/api/v3/openapi.json",
      "base_url": "https://petstore3.swagger.io/api/v3",
      "security_credentials": {
        "api_key": { "value": "env.PETSTORE_API_KEY" }
      }
    }
  }'

The env.PETSTORE_API_KEY reference needs an authenticated admin session: when dashboard authentication is disabled or unconfigured, env. and vault. references in security_credentials are refused with 403 (literal values are accepted). spec (inline text) can be sent instead of spec_url. A spec_url is fetched once and stored with the server. Unknown names in tools_to_execute are rejected with 400, as are auth_type values other than none, headers and per_user_headers.Replace the document on an existing server with PUT /api/mcp/client/{id}. The block is merged onto the stored one: every field you leave out keeps its stored value, including include_deprecated and max_response_bytes, and a redacted credential keeps the stored secret. An empty base_url removes the override, an empty spec_url removes the stored URL, and a security_credentials map replaces the stored set (schemes left out are removed). Renaming the server re-checks tools_to_execute, since long tool names are shortened to fit beside the name. Replace {id} with the server’s ID, and pass the new document as a JSON-escaped string:

curl -X PUT "http://localhost:8080/api/mcp/client/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-session-token>" \
  -d '{
    "openapi_config": { "spec": "<new document text>" },
    "tools_to_execute": ["*"]
  }'

GET /api/mcp/client/{id}/openapi-spec returns the stored document; GET /api/mcp/clients leaves it out and reports spec_title, openapi_version, spec_size, spec_hash and operation_count instead.

When dashboard authentication is disabled or unconfigured, spec_url and base_url must resolve to public addresses, the same rule that applies to an HTTP server’s connection_string.

{
  "mcp": {
    "client_configs": [
      {
        "name": "petstore",
        "connection_type": "openapi",
        "auth_type": "headers",
        "headers": { "X-Tenant": "acme" },
        "tools_to_execute": ["getInventory", "getPetById"],
        "openapi_config": {
          "spec_file": "specs/petstore.yaml",
          "base_url": "https://petstore3.swagger.io/api/v3",
          "security_credentials": {
            "api_key": { "value": "env.PETSTORE_API_KEY" }
          },
          "include_deprecated": false
        }
      }
    ]
  }
}

openapi_config needs at least one document source, used in this order of precedence: spec (inline text), spec_file (a path relative to the config directory, read at load), then spec_url (fetched at every connect when neither of the others is set). Next to spec, spec_url records where the document came from and resolves its relative servers, so keep it when the document uses them. Editing the document, base URL or credentials in config.json is picked up on the next restart like any other client change.

​

Go SDK

import "github.com/maximhq/bifrost/framework/openapimcp"

cfg.MCPConfig.InProcessServerFactory = openapimcp.Factory(openapimcp.WithConfigDir("/etc/bifrost"))

​

Limitations

• One tool per operation; very large documents produce many tools. Above 128 tools the preview warns: restrict tools_to_execute to limit what the model sees. Above 1000 tools the document is rejected before any allow-list applies; reduce the document to at most 1000 supported operations.
• File uploads, binary and streaming bodies, OAuth-only APIs and externally referenced schemas are not supported (see above).
• The gateway exposes tools as <server>-<tool> within 64 characters, so long operationIds are shortened. A server name that leaves fewer than 16 characters for the tool (longer than 47 characters) is rejected for OpenAPI servers.
• A redirect to another host, or from https to plain http, is not followed when the call carries credentials, custom headers or query parameters; the model receives the redirect response instead, so credentials never reach a host the document did not name or travel unencrypted.
• Tool names depend on the document’s operationIds. With a partial selection, renamed and newly added tools stay unselected until you tick them. If all previous tools were selected, every supported tool in the replacement document is selected, renamed and newly added ones included.

​

Next Steps

• Filtering to scope which tools each caller sees.
• Tool Execution for how calls are run and timed out.
• Authentication for static and per-user headers.