Prepare your OpenAPI spec | MCP Stack Docs

MCP Stack

The OpenAPI spec is the source material for a generated MCP server. MCP Stack can work with normal OpenAPI 3.0 and 3.1 documents, but the quality of the generated tools depends on the quality of the operation names, descriptions, schemas, auth metadata, and server URLs.

OpenAPI to MCP Stack generation visual

The generator reads your API contract, turns selected operations into MCP tools, and keeps auth metadata available for Gateway or static runtime auth.

Minimum requirements#

Have these before you start the dashboard wizard:

Requirement	Why it matters
Public OpenAPI URL	The dashboard wizard imports specs from URLs. Use the CLI when the spec is only available as a local file.
OpenAPI 3.0 or 3.1	The parser expects modern OpenAPI structure.
Correct `servers` entry	Generated tools need a base URL for upstream API calls.
Stable `operationId` values	These become better tool names than generated path names.
Request and response schemas	Agents need precise input contracts and useful result structure.
Security schemes	MCP Stack uses them to recommend Public API, Static Headers, or Gateway.

A strong operation#

Give every important operation a stable operationId, a direct summary, a practical description, and complete parameters.

YAML

paths:
  /tickets/{ticketId}/notes:
    post:
      operationId: createTicketNote
      summary: Add a note to a support ticket
      description: >
        Adds an internal note to the ticket timeline. Use this only after
        the user confirms the ticket and note content.
      tags:
        - Tickets
      parameters:
        - name: ticketId
          in: path
          required: true
          schema:

Security scheme examples#

Use OpenAPI security metadata even if the API works without it in local development. MCP Stack uses this signal to recommend the right runtime auth mode.

YAML

components:
  securitySchemes:
    userOAuth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/oauth/authorize
          tokenUrl: https://auth.example.com/oauth/token
          scopes:
            tickets.read: Read tickets
            tickets.write: Update tickets

For static API keys:

YAML

components:
  securitySchemes:
    upstreamApiKey:
      type: apiKey
      in: header
      name: X-API-Key

Clean up before import#

Review the spec for:

Duplicate operationId values.
Missing request body schemas.
Placeholder servers like http://localhost:3000.
Admin-only paths that should not be tools.
Internal endpoints that are only useful to backend services.
Overly broad tags like Default for every operation.
Vague summaries like "Update" or "Get".

Do not use OpenAPI as an access policy

The spec helps MCP Stack generate and describe tools, but it is not your final security boundary. Use Gateway, scopes, downstream API checks, and tool selection to keep the runtime safe.

If the spec is private#

The dashboard wizard and server settings support private specs directly. If your spec is private:

Paste JSON/YAML into the dashboard wizard, or upload .json, .yaml, or .yml.
Use the CLI with a local file for scripted create/update flows.
Let MCP Stack Host publish the hosted runtime automatically.

BASH

mcpstack servers create --openapi-file ./openapi.yaml
 
mcpstack servers update <server-id> --openapi-file ./openapi.yaml

Recommended spec review#

Before giving the server to developers or agents, check:

The generated tool names read like actions.
Each write operation has a description that says what will change.
Required fields are actually required in the schema.
Enum values are documented.
The upstream base URL is production or staging, not localhost.
OAuth scopes are narrower than "everything".

Quick answer#

If the generated tools look odd, inspect the OpenAPI source first. Check the operation name, path, operationId, description, schemas, servers, and securitySchemes. Most generation quality issues start there.