Use a config file so the header name is explicit:

servers:
  - name: petstore
    spec: https://petstore3.swagger.io/api/v3/openapi.json
    auth:
      type: api_key
      token: ${PETSTORE_API_KEY}
      api_key_header: api_key

The MCP spec requires a server to accept only tokens minted for itself, and forbids relaying one to an upstream API. So under both protected flows the upstream is reached with a second, separately obtained credential rather than the one the caller presented. See Access Token Privilege Restriction.

passthrough is the one exception, and it exists for the FastAPI integration, where the gateway runs in-process as part of the app it exposes. There is no separate upstream to be confused about. Setting it against a genuinely separate API is the confused-deputy pattern the spec forbids, which is why nothing selects it automatically.

An API with no authorization server of its own, which accepts tokens from a provider the deployment already runs, needs the gateway to say which API its upstream token is for. Point the OAuth URLs at that provider and name the API:

servers:
  - name: internal
    spec: https://internal.example.com/openapi.json
    auth:
      type: oauth2
      flow: authorization_code
      upstream:
        authorization_url: https://you.auth0.com/authorize
        token_url: https://you.auth0.com/oauth/token
        client_id: ${GATEWAY_CLIENT_ID}
        client_secret: ${GATEWAY_CLIENT_SECRET}
        audience: https://internal.example.com

Without it the provider mints for its own default audience and the API refuses the result. The parameter rides on the authorization request and on every token request, refreshes included, so a rotated token stays usable.

Authorization servers disagree on the spelling. upstream.audience is what Auth0 expects, upstream.resource is the RFC 8707 parameter.

Set the one yours reads, or set both. A server that does not recognise a parameter ignores it silently rather than refusing, so Keycloak given only upstream.resource returns a perfectly ordinary token whose audience is wrong, and the upstream then rejects it for reasons that look unrelated. Sending both is legal, since RFC 8707 §2.1 defines both names, and it is the portable choice.

MCP clients still authorize against the gateway and receive a gateway-issued token, while the provider-issued one is a second credential held on their behalf. End users see whatever login the provider federates to, so this works on any plan and needs nothing of the upstream but that it accept what the provider issues.

The Auth0 Management API is a worked example of exactly this shape, since its own audience differs from the tenant that issues for it. See examples/auth0-management.yml.

authorization_code leaves the gateway issuing credentials of its own, so revoking someone at the provider has no effect until the gateway's token expires. token_exchange removes that second issuer. The provider mints tokens for the MCP endpoint directly, the gateway validates them, and each call exchanges one under RFC 8693 for a second token naming the upstream:

servers:
  - name: internal
    spec: https://internal.example.com/openapi.json
    auth:
      type: oauth2
      flow: token_exchange
      issuer: https://auth.example.com/realms/internal
      upstream:
        audience: https://internal.example.com
        client_id: ${GATEWAY_CLIENT_ID}
        client_secret: ${GATEWAY_CLIENT_SECRET}

The gateway serves no /authorize or /token here. Its protected resource metadata names the issuer, clients authorize there, and the JWKS comes from the issuer's own metadata so key rotation needs no restart.

The endpoint identifies itself as {url}{mount_path}/mcp, built from the gateway's url and the server's mount path, so the example above is https://gw.example.com/internal/mcp. That exact string is what an inbound token's aud must contain, so you need it when creating the matching client and audience mapping at the issuer.

Two things to check before committing to this mode. Token exchange support varies:

Keycloak is generally available in the sense that the feature flag is on, but a working realm still needs three things that its documentation does not connect to this use case:

• The inbound aud comes from an audience mapper, added to a client scope. Keycloak ignores resource and audience on the authorization and token endpoints, so without a mapper the token's audience is just account and the gateway rejects it.
• The client performing the exchange must itself be in the subject token's audience, or the exchange fails with access_denied: Client is not within the token audience. The tidiest arrangement is to make the MCP endpoint a client whose clientId is its canonical URI, so it is both the audience target and the exchanging client.
• The exchange target must exist as a client and be reachable from the exchanging client's scopes, or the exchange fails with invalid_request: Requested audience not available.

And because the issuer is the authorization server for this endpoint, MCP clients register there rather than with the gateway. Check whether yours supports dynamic client registration, or whether each client needs pre-registering. If it does support it, set required_scopes so the advertised scopes_supported tells a registering client what to ask for. Leave it empty and a client may register with a minimal scope set whose tokens then carry neither the audience nor the claims the upstream needs.

Under authorization_code the gateway's own access token lives 1 hour and its refresh token 24 hours. Each refresh issues a fresh refresh token, so the refresh TTL is the practical re-authorization cadence. A client refreshing within it never signs in again, while one idle past it must re-authorize. Tune both with auth.mcp_access_token_ttl and auth.mcp_refresh_token_ttl.

token_exchange mints nothing, so neither applies. Lifetimes are the issuer's to set.

policy:
  allow: ["GET /repos/*"]
  deny:  ["GET /repos/*/actions/secrets*"]

Operations can also be opted in from the spec side with x-mcp-integration: {tool: {}} plus policy.annotated_only: true. Filters apply in the order annotated_only, then allow, then deny.

To rename a resource, set a custom URI template, or set a non-JSON MIME type, use the operations map keyed by operationId:

servers:
  - name: petstore
    spec: https://petstore3.swagger.io/api/v3/openapi.json
    exposure:
      promote_resources: true
    operations:
      getPetById:
        resource:
          name: pet
          mime_type: application/json
      getInventory:
        resource:
          name: inventory

If you own the upstream spec, write the same opt-in inline instead:

paths:
  /pets/{petId}:
    get:
      operationId: getPet
      x-mcp-integration:
        resource:
          name: pet
          mime_type: application/json
          # uri_template: petstore://v2/pets/{petId}  # optional, must start with "<server>://"

Declaring both tool and resource registers the operation on both surfaces. Each entry fully replaces (does not merge with) the spec-side x-mcp-integration. A runnable demo lives at examples/petstore-override.yml.

An unknown operationId raises at startup so typos do not silently no-op. Resource declarations are validated there too, so non-GET methods, required non-path parameters, and uri_template values that do not start with <server>:// abort Gateway.from_config with a concrete error. Subscriptions are not implemented because REST has no native push.

servers:
  - name: github
    spec: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
    operations:
      pulls/list-files:
        tool:
          name: list_pull_request_files
          description: |
            List files changed in a pull request. Returns up to 3000 files,
            each with status (added / modified / removed), patch text, and
            line counts.

If you own the upstream spec, write the same block inline as x-mcp-integration.tool on the operation.

The input layer is declarative and the value transforms are JSONata expressions.

params and params_strategy shape what the model sees. Each params entry is a JSON Schema fragment (type, enum, default, description, format, minimum, items, and so on) plus two flags. required lifts the parameter into the schema's required list, and hidden removes a spec parameter from the surface. params_strategy is mandatory whenever params is set:

• merge: tweaks the operation's existing parameters and keeps the rest visible, so declaring a parameter the spec does not define is an error.
• replace: makes the declared entries the whole schema and drops every spec parameter, so it always needs a request to route the friendly arguments upstream.

operations:
  searchIssues:
    tool:
      params_strategy: merge
      params:
        internal_flag: { hidden: true }
        per_page: { default: 30 }
        sort: { description: "One of comments, created, updated." }

request and response transform the values. Both are optional and independent of each other. request builds the entire upstream request, and response reshapes a successful body before it reaches the client.

operations:
  searchIssues:
    tool:
      request: |
        $merge([$, { "per_page": 30, "state": "open" }])
      response: |
        [items.{ "title": title, "url": html_url }]

• Routing: a key that names a path placeholder fills the path, and the rest become query parameters for a body-less method or the JSON body otherwise.
• Passthrough: $merge([$, { ... }]) forwards the incoming arguments and overrides only the keys you name, as above.
• Lists: wrapping a mapping in [ ... ] keeps the result an array even when a single item matches.
• Errors: a broken expression is rejected at startup, and a runtime failure returns an isError result naming the side that broke.

For a full replace example, where the declared params are the entire surface and request maps a friendly enum onto the raw query with $lookup, see examples/movie-shaping.yml.

• list_operations() returns [{name, description}, ...] for every operation on this server.
• get_operation(name) returns one operation's JSON Schema for input arguments.
• call_operation(name, arguments) invokes that operation against the upstream.

Auth, path templating, and per-operation request shape match static mode, so only the surfacing changes. See examples/github-dynamic.yml for a runnable config.

Because the gateway runs in-process and routes through httpx.ASGITransport, gateway and upstream share the same OAuth audience, so the MCP client's Authorization header passes through verbatim (auth.type: passthrough, set automatically for this integration only). For client_credentials schemes the gateway mints upstream tokens from its own credentials instead.

from fastapi import FastAPI
from openapi_mcp_gateway import Gateway, GatewayConfig, ServerConfig

app = FastAPI()

gateway = Gateway.from_config(
    GatewayConfig(
        url="https://your-app.example.com",  # public URL, used for discovery and redirect URLs
        servers=[ServerConfig(name="petstore", spec="petstore.json")],
    )
)
gateway.mount(app)  # mounts /petstore/mcp plus its OAuth and .well-known routes

Set GatewayConfig.url to the host app's public URL so discovery documents and OAuth redirect URLs point at the right origin. The upstream OAuth callback for a server named <server> is fixed at /<server>/auth/callback, so keep it clear of your app's own callback paths.