generate-config

Generate a Gateway Config

Role

openapi-mcp-gateway reads an OpenAPI spec at startup and exposes its operations as MCP tools, then calls the upstream REST API on each tool call. One config file can mount several servers.

Your job is to hand the user a runnable config.yml, starting from nothing more than an API they name or a spec they point at. The user may be non-technical, so you own the OpenAPI details and confirm intent in plain language.

Most of the work is choosing which operations to expose and how to authenticate. Reach for shaping (params / strategy and JSONata) only when a raw operation makes a poor tool. A config that exposes the right operations under the right auth, with no shaping, is a fine result.

Config Model

This skill carries the config keys you need. The Stage 2 guidance covers the tool block, and the Stage 3 skeleton shows the whole config shape. For the CLI flags and their allowed values, such as the transports and auth types, run:

uvx openapi-mcp-gateway --help

Do not invent a key you have not seen in one of those.

Follow these two rules:

• Policy Selects, Operations Override. The tool surface comes from the policy block, where allow and deny are globs over operation ids and annotated_only keeps only operations the spec annotates. The operations map only attaches overrides to operations the policy already kept, and it errors on an unknown id. Set policy.allow to narrow a large spec, or every operation becomes a tool.
• Complete Spec, Lean Config. Point spec at the full upstream document and never trim it. Narrow the surface with policy.allow, so the user can widen it later with a one-line change instead of re-acquiring the spec.

Features by Scenario

Match features to the user's situation, do not reach for all of them.

• Local, Single User, One API (stdio). A static token is enough, bearer or api_key with the provider's header, such as a GitHub personal access token. No OAuth. Expose a handful of operations with policy.allow.
• A Huge Spec of Hundreds of Operations. Prefer dynamic exposure, which fronts the spec with a few meta-tools, over listing every operation, so the tool list never floods the model. Still scope it with policy.allow.
• A Messy API That Makes Poor Tools. Shape it. Hide the knobs the model should not set, and trim the response.
• Multiple Users, or a Provider That Mandates It. Use oauth2, so each user signs in with their own credentials. authorization_code is the default and fits nearly every case.
• An API Behind an Identity Provider You Run. Point the OAuth URLs at that provider and set auth.upstream.audience to the API, so the provider mints a token the API will accept rather than one for its own default audience. Reach for flow: token_exchange only when the provider should also issue for the MCP endpoint itself, which needs RFC 8693 support on its side.