OpenAPI & Swagger

Introduction

OpenAPI/Swagger servers let you expose an existing REST API as MCP tools without writing any code. Gatana reads an OpenAPI or Swagger specification and automatically generates one tool per API operation. When an AI client calls a tool, Gatana translates the call into the corresponding HTTP request and returns the response.

Both OpenAPI 3.x and Swagger 2.0 specifications are supported.

Providing the Specification

There are two ways to supply the specification:

• Remote Spec URL: Provide a URL to a hosted OpenAPI/Swagger document. Gatana fetches the spec from this URL and keeps it updated automatically, so changes to your API are picked up over time.
• Manual Spec: Paste the specification directly. Use this when the spec is not publicly reachable or when you want to pin an exact version.

When using a remote URL, you can use the Test button to validate the spec before saving. It reports the API title and version, the detected spec version, the number of operations found, and a preview of the resolved endpoints.

Configuration Options

• Spec URL / Spec — The source of the OpenAPI/Swagger document (see above).
• Base URL Override (Optional) — By default the base URL is derived from the spec (the servers entry for OpenAPI 3.x, or host + basePath + schemes for Swagger 2.0). Set this to override the target endpoint, for example to point at a staging environment. Trailing slashes are stripped.
• Headers — Custom HTTP headers sent with every request, useful for authentication (e.g. an Authorization header) or other fixed values your API requires.

See the Credentials page for more information about configuring authorization and credentials.

How Tools Are Generated

Each operation (path + HTTP method) in the specification becomes a single MCP tool:

• Tool name — Derived from the operation's operationId (sanitized to a valid tool name). If no operationId is present, a {method}_{path} name is generated, and any collisions are de-duplicated.
• Title and description — Taken from the operation's summary and description.
• Input schema — Built from the operation's path, query, and header parameters. If the operation defines a request body, a required body property is added. Path-level parameters are merged in, and operation-level parameters override them. Local $refs to components/definitions are resolved and embedded so the schema is self-contained.

When a tool is invoked, Gatana substitutes path parameters, appends query parameters (arrays become repeated query values), applies header parameters and configured headers, serializes any JSON request body, and performs the HTTP request against the base URL. JSON responses are parsed and returned; a non-2xx response results in an error that includes the response body.