DEV Community: MrOops

openapi-mcp-gateway: Resources, Dynamic Exposure, and Spec-Compliant Auth

MrOops — Tue, 09 Jun 2026 15:36:32 +0000

The first post on openapi-mcp-gateway closed with a roadmap. The resource primitive and dynamic exposure both shipped, plus a few more worth writing down. All in v0.5.0:

Dynamic exposure for huge specs like GitHub
Auto-promote eligible GETs to MCP resources
MCP spec compliance (audience-bound auth + protocol-native tool metadata)
Tool name and description override

Try It

One config exercising every new surface:

# servers.yml
host: 0.0.0.0
port: 8000

servers:
  # Eligible GETs become MCP resources; everything else stays a tool.
  - name: petstore
    spec: https://petstore3.swagger.io/api/v3/openapi.json
    base_url: https://petstore.swagger.io/v2
    mode: auto

  # ~1,200 ops behind three meta-tools instead of 1,200 schemas in tools/list.
  - name: github
    spec: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
    exposure: dynamic
    auth:
      type: bearer
      token: ${GITHUB_TOKEN}

  # Per-user OAuth2, audience-bound tokens, no passthrough.
  - name: asana
    spec: https://raw.githubusercontent.com/Asana/openapi/master/defs/asana_oas.yaml
    auth:
      type: oauth2
      client_id: ${ASANA_CLIENT_ID}
      client_secret: ${ASANA_CLIENT_SECRET}
      scopes: [openid, email, profile, users:read]

uvx openapi-mcp-gateway --config servers.yml

What you get at http://127.0.0.1:8000:

/petstore/mcp: 13 tools + 6 resources (3 concrete, 3 templates), partitioned by mode: auto with no spec edits.
/github/mcp: three meta-tools (list_operations, get_operation, call_operation) fronting ~1,200 endpoints.
/asana/mcp: per-user OAuth2 against Asana's IdP.

1. Dynamic Exposure: Three Meta-Tools for Huge Specs

GitHub's REST API spec carries 1,190 operations. Static registration ships every name, description, and JSON Schema at connect time. At ~300 tokens per tool that is 350K+ tokens in tools/list alone, larger than any frontier model's context window, before the agent makes a call.

servers:
  - name: github
    spec: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
    exposure: dynamic
    auth:
      type: bearer
      token: ${GITHUB_TOKEN}

The client now sees three tools instead of 1,190:

async def list_operations(ctx: Context) -> CallToolResult:
    # returns: {"operations": [{"name": str, "description": str}, ...]}

async def get_operation(name: str, ctx: Context) -> CallToolResult:
    # returns: {"name": str, "description": str, "input_schema": JSONSchema}

async def call_operation(name: str, arguments: dict[str, Any], ctx: Context) -> CallToolResult:
    # returns: upstream response wrapped as CallToolResult

The agent walks them in order:

list_operations() to discover.
get_operation("issues_create") to read the schema for the one it wants.
call_operation(name, args) to invoke.

Auth, path templating, and per-operation request shape are identical to static mode. Only the surfacing changes.

When NOT to Use It

Dynamic exposure adds two round trips before the first real call. For small specs that fit comfortably in context, those round trips are pure latency tax.

Rough rule of thumb (the numbers are guidance, not benchmarks):

Operation Count	Recommended Mode
Under ~30	`static`
30 to ~100	`static` + `policy.allow` narrowing to the hot subset
Over ~100	`dynamic`

It is a per-server flag, so /github/mcp can run dynamic while /petstore/mcp runs static in the same gateway.

2. Resources Are a Primitive, and Most GETs Should Be One

Tools are actions. The client picks one, fills in arguments, and the result enters the conversation. Most OpenAPI-to-MCP gateways register every operation that way. But MCP has a second primitive. Resources are addressable content returned as text or blob, and a GET /pets/{petId} or GET /store/inventory is a far better fit for the resource shape than the tool shape.

Mode: Auto

servers:
  - name: petstore
    spec: https://petstore3.swagger.io/api/v3/openapi.json
    mode: auto

At startup the gateway partitions every operation:

Operation Shape	Becomes
GET, no required `query` / `header` / `body`	Resource
Everything else (POST, PUT, DELETE, GET with required args)	Tool

Vanilla Petstore3 produces 13 tools, 3 concrete resources, and 3 resource templates. The default mode: tool_only keeps everything as tools.

Per-Operation YAML Overrides

When you want finer control without forking the spec, layer overrides in the same server YAML. Common reasons:

Rename a resource
Set a custom URI template
Set a non-JSON MIME type

servers:
  - name: petstore
    spec: https://petstore3.swagger.io/api/v3/openapi.json
    mode: auto
    operations:
      getPetById:
        expose:
          resource:
            name: pet
            uri_template: petstore://v2/pet/{petId}
      getInventory:
        expose:
          resource:
            name: inventory

Keys match operationId. Unknown ids raise at startup so typos do not silently no-op. Each entry fully replaces any spec-side x-mcp-integration for that operation. This is the path when the upstream spec belongs to a vendor or a different team.

Spec-Side Opt-In

If you own the spec, the same opt-in fits inline as x-mcp-integration.expose.resource on the operation. All three paths (mode, YAML, spec) land in the same registration:

Spec Shape	Registered As	Example URI
GET with path params	Resource Template	`petstore://pet/{petId}`
GET without path params	Concrete Resource	`petstore://store/inventory`

Auth, base URL, and retries are shared with the tool path.

3. MCP Spec Compliance

The 2025-11-25 MCP spec tightened requirements on two fronts: how the server handles tokens it forwards upstream, and what shape it returns tool results in. Both shipped in v0.5.0.

Audience-Bound Auth

A naive gateway forwards the MCP client's token straight to whatever third-party upstream the tool eventually hits. That is the token passthrough anti-pattern, and the spec explicitly forbids it.

The new default:

Gateway is an OAuth client to the upstream and mints upstream tokens server-side for authorization_code and client_credentials.
MCP client's token is never forwarded to a different audience.
Tokens are bound to the gateway's canonical resource URI per RFC 8707.
Passthrough is opt-in (auth.flow: passthrough) and only safe when gateway and upstream share the same audience. The FastAPI integration is the one place this opts in automatically.

If authorization_code is configured without client_id / client_secret (i.e. you meant to mint upstream tokens but forgot credentials) the gateway logs an INFO message and falls back to passthrough. Set the credentials, or set auth.flow explicitly.

Protocol-Native Tool Metadata

The other half is what comes back in tools/call. Generated tools now emit:

Field	Source	Effect
`title`	OpenAPI `summary`	Clients show "Fetch one pet by id" instead of `getPetById`.
`annotations`	HTTP method	`readOnlyHint` for GET, `destructiveHint` for DELETE, `idempotentHint` for GET/PUT/PATCH/DELETE.
`structuredContent`	Parsed JSON body (success and error)	Agent reads error codes etc. without re-parsing the text body.

Tool callables also return CallToolResult directly. Upstream 4xx/5xx no longer raises out of the tool. It returns isError=True with the parsed body in structuredContent. The agent can read the error code, retry with backoff, or surface a useful message. Network failures get the same treatment.

4. Tool Name and Description Override

Two recurring problems with OpenAPI specs in the wild:

Ugly operationIds. The GitHub spec ships actions/list-jobs-for-workflow-run-attempt and packages/get-all-package-versions-for-package-owned-by-authenticated-user.
Empty descriptions. Most of the GitHub gists/* endpoints (gists/delete, gists/list-commits, gists/fork, ...) ship with description: "".

The LLM has to guess intent from the name alone. Override via x-mcp-integration.expose.tool:

x-mcp-integration:
  expose:
    tool:
      name: list_gist_commits
      description: |
        List commits for a Gist. Returns up to 30 commits per page with
        commit SHA, author, and timestamp. Use ?page= for pagination.

Cheap fix with outsized impact when the agent picks the wrong tool because two operations had near-identical default descriptions.

Closing

Still a side project. The recurring situations driving this work:

Huge specs eating context.
GETs that want to be resources.
B2B APIs that want real per-user auth.

The answers turned out worth writing down. If any of this was useful, a star on the repo would mean a lot. It is the clearest signal back that this is solving real problems for other people, and it is what keeps the next release coming.

Repository: github.com/mroops0111/openapi-mcp-gateway
PyPI: pypi.org/project/openapi-mcp-gateway (v0.5.0)
First Post: I Built openapi-mcp-gateway

OpenAPI-to-MCP, Done Right: Multi-Spec APIs and Real OAuth2

MrOops — Sun, 10 May 2026 15:21:31 +0000

This gateway started as a demo. The job was to turn our company's OpenAPI spec into an MCP server so non-technical product folks could try the API through Claude Desktop. The naive version came together quickly.

Then the demo grew. For a customer-support-style agent to be useful, it needed to chain our product API with the internal issue tracker, and both gate access on the user's identity, not a shared service token. The audience was non-technical, so streamable HTTP was the floor. But I did not know what the eventual production client would be, so I wanted stdio and SSE on the same binary as well. And because the spec was actively changing, I needed the MCP layer to track it automatically rather than be hand-maintained.

By the time everything ran stably (multi-API, real per-user OAuth2, all three MCP transports, auto-regenerated from the spec), I had built openapi-mcp-gateway.

It is a Python service that turns OpenAPI specs into MCP servers, mounts as many of them as you want in one process, and does real per-user OAuth2 with token relay. You point it at a YAML and it runs.

Try It

uvx openapi-mcp-gateway --spec https://petstore3.swagger.io/api/v3/openapi.json --name petstore
# MCP server live at http://127.0.0.1:8000/petstore/mcp

Or add it as a dependency:

uv add openapi-mcp-gateway

Connect from Claude Desktop, Cursor, Cline, or any other MCP client. Streamable HTTP, SSE, and stdio are all supported. Python 3.11+.

What The Gateway Actually Does

Three things, each shown in code.

1. Multiple APIs In One Process

Most agent tasks touch more than one API. GitHub for repo lookups, your internal product API for the actual work, an external CRM. Point a single YAML at all of them:

# servers.yml
host: 0.0.0.0
port: 8000
url: http://localhost:8000

servers:
  - name: petstore
    spec: https://petstore3.swagger.io/api/v3/openapi.json

  - name: github
    spec: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
    auth:
      type: bearer
      token: ${GITHUB_TOKEN}
    policy:
      allow: ["GET /repos/*", "GET /users/*"]
      deny:  ["GET /repos/*/actions/secrets*"]

  - name: asana
    spec: https://raw.githubusercontent.com/Asana/openapi/master/defs/asana_oas.yaml
    auth:
      type: oauth2
      client_id: ${ASANA_CLIENT_ID}
      client_secret: ${ASANA_CLIENT_SECRET}
      scopes: [openid, email, users:read, workspaces:read]

uvx openapi-mcp-gateway --config servers.yml

Three MCP servers at /petstore/mcp, /github/mcp, /asana/mcp. Each with its own auth. Each independently filterable with policy.allow / policy.deny, so you do not blast every endpoint of every spec at the model.

Visually, this YAML produces:

One process, three mount paths, three different auth backends, three different upstream identities. None of them leak into each other.

2. Real Per-User OAuth2 (Token Relay)

This is the constraint that drove most of the design. When a user opens Claude Desktop and connects to one of the mounted servers:

The gateway plays two roles at once, acting as an OAuth Authorization Server to the MCP client and as an OAuth Client to the upstream API. It mints its own MCP-scoped tokens with their own TTLs and revocation, and keeps a private mapping from those tokens to the upstream tokens.

The result is the part that matters. The MCP client never holds a credential for an API it does not know about, and the upstream API's audit log shows the actual end user.

And because every mounted server has its own auth config, one gateway process can run several different OAuth setups in parallel: Asana OAuth on /asana/mcp, GitHub bearer on /github/mcp, your internal OAuth on /myapp/mcp, all at once. Three different upstream identities, three independent OAuth flows, no cross-talk in the token store, the auth resolver, or the request path. The Asana token issued to one user cannot be confused with the GitHub bearer used to look up a repo. Each (server, user) pair lives in its own namespace.

For service-to-service calls, client_credentials is also supported, with lazy fetch and concurrent-refresh dedup under an asyncio.Lock so N concurrent tool calls hitting the gateway at expiry produce exactly one IdP request. Different shape, different OAuthFlowHandler.

3. FastAPI-Native `@mcp_tool`

Beyond raw OpenAPI specs, the gateway also takes a live FastAPI app as input. If you already have one, decorate the routes you want exposed:

from fastapi import FastAPI
from openapi_mcp_gateway import Gateway, mcp_tool

app = FastAPI()

@app.get("/items/{item_id}")
@mcp_tool()
def read_item(item_id: int):
    return {"id": item_id}

@app.get("/internal/health")  # not decorated, not exposed
def health():
    return {"ok": True}

Gateway.from_fastapi(app, name="myapp").run()

Tool calls run in-process through httpx.ASGITransport. No localhost roundtrip, no parallel spec, no separate uvicorn. Auth is auto-detected from the app's securitySchemes.

How It Compares To Existing Tools

I did the homework, so you do not have to. As of May 2026, here is the OpenAPI-to-MCP converter landscape (tools whose primary job is "take an OpenAPI spec, produce an MCP server"):

	mroops0111/openapi-mcp-gateway	fastapi_mcp	awslabs/mcp	ivo-toby	harsha-iiiv	ckanthony
Language	Python	Python	Python	TS	TS (codegen)	Go
Input	OpenAPI or FastAPI app	FastAPI app only	OpenAPI	OpenAPI	OpenAPI	OpenAPI
Multi-spec in one process	Yes (YAML)	No	Yes	No	No	No
OAuth2 authorization_code w/ relay	Yes	Yes	Cognito only	Yes	No	No
OAuth2 client_credentials	Yes (lazy + lock)	Not documented	No	Yes	Yes	No
stdio + SSE + Streamable HTTP	All three	SSE + StrHTTP	stdio	Partial	All three	Single port
FastAPI-native decorator	Yes	Whole-app only	No	No	No	No
Pluggable Redis token store	Yes	No	No	No	No	No

Reading guide:

If your only input is a FastAPI app, fastapi_mcp is more focused than mine. The in-process ASGI trick is its native idea, and I borrowed it for @mcp_tool.
If you need multi-spec on AWS and Cognito is your auth, awslabs/mcp is purpose-built for that.
If you want a TypeScript runtime, ivo-toby/mcp-openapi-server is the closest analogue.
If you want a generated Node project you control end-to-end, harsha-iiiv/openapi-mcp-generator is the right shape.
If you want a Python service you point at a YAML, that hosts several specs at once, that does both OAuth2 flows on real upstream providers (not just Cognito), and that has a decorator for the FastAPI app you probably already have, this gateway is for you.

Concretely, this gateway tends to be the right fit in three situations:

Internal agents that have to touch several in-house APIs. Customer support, finance ops, IT helpdesk. The agent needs your product API plus your issue tracker plus maybe your CRM, each with its own auth. One process, several mounts, no inter-service leakage.
B2B APIs where actions need to happen as the actual end user. Signing a contract, moving money, closing a ticket on someone's behalf. Anything where the audit log on the upstream side has to show the human, not a shared service account. The token relay handles the per-user identity end to end.
Demo or PoC stage with a moving spec. The OpenAPI spec is still evolving, you do not yet know what the production MCP client will be, and you do not want to hand-maintain an MCP server in parallel. Point the gateway at the spec, get all three transports for free, regenerate every time the spec changes.

What Is And Is Not There Yet

Shipping today: OAuth2 authorization_code with token relay, OAuth2 client_credentials with concurrency primitives, multi-server in one process (each with independent auth), FastAPI-native @mcp_tool, operation filtering (allow / deny / marked_only), Redis token store, all three MCP transports.

On the roadmap, in case any of these would unblock you:

Flexible OAuth2 scope mapping. Today, upstream scopes pass through to MCP one-to-one. Some setups need to expose only a subset, alias names, or group several upstream scopes under one MCP-side scope. Configurable in YAML, per server.
Merging multiple OpenAPI specs into one MCP server. Today one spec produces one mounted server. Some upstream APIs split a single product's docs across several spec files (by tag, by version, by section), and forcing the agent to pick across N mount paths for what is logically one API is awkward. Want a specs: list that the gateway combines into a single MCP server.
MCP primitives beyond tools, with per-operation YAML overrides. Today every operation in your spec becomes an MCP tool. MCP also has resources, prompts, and sampling, and not every operation is best modelled as a tool (GET /users/{id} is more naturally a resource than a tool). Want a YAML override per operation, which lets you choose the MCP primitive, rename it, hide it, or reshape its inputs.
Dynamic tool exposure (skill-style discovery). For large APIs with hundreds of operations, registering every operation as its own tool blows the agent's context window before the agent has done anything. Want an opt-in mode where the gateway exposes only three meta-tools (list, get, call), and the agent fetches operation details on demand. Same pattern as agent skills.

If any of these are blocking you, please open an issue with the shape of your problem. Concrete use cases drive the design more than my guesses.

Closing

This is a personal open-source side project, not anything I deploy at work. The constraints came from the kinds of agent flows I think about because of my dayjob (a B2B e-signature API), but the gateway itself is independent of that. Sharing it here in case the situations above sound like yours.

Repository: github.com/mroops0111/openapi-mcp-gateway
PyPI: pypi.org/project/openapi-mcp-gateway

DEV Community: MrOops

openapi-mcp-gateway: Resources, Dynamic Exposure, and Spec-Compliant Auth

Try It

1. Dynamic Exposure: Three Meta-Tools for Huge Specs

When NOT to Use It

2. Resources Are a Primitive, and Most GETs Should Be One

Mode: Auto

Per-Operation YAML Overrides

Spec-Side Opt-In

3. MCP Spec Compliance

Audience-Bound Auth

Protocol-Native Tool Metadata

4. Tool Name and Description Override

Closing

OpenAPI-to-MCP, Done Right: Multi-Spec APIs and Real OAuth2

Try It

What The Gateway Actually Does

1. Multiple APIs In One Process

2. Real Per-User OAuth2 (Token Relay)

3. FastAPI-Native @mcp_tool

How It Compares To Existing Tools

What Is And Is Not There Yet

Closing

3. FastAPI-Native `@mcp_tool`