DEV Community: MrOops

Turn a Codebase into a Domain Model Your PM and QA Can Read

MrOops — Tue, 18 Aug 2026 10:05:29 +0000

Every team I have worked on keeps two versions of the same product in its head.

One is the code. It is honest about what actually runs, but it speaks in class names and package paths. A PM cannot read it, and even an engineer new to the service cannot tell from it why a rule exists or who asked for it.

The other is the intent. It lives in PRDs, design docs, Notion, and an old Slack thread no one can find. It speaks the language of the business, but nobody keeps it in sync once the code lands. Before long, no one trusts it, and everyone ends up back at an engineer's desk to confirm what is actually true.

These two drift apart every sprint, and the team ends up arguing about which one is right. Braid is my attempt to stop that argument by keeping a single model both sides can read. It is a framework. You bring the sources and pick an ontology, and it runs a loop where the AI drafts and asks, and people decide.

The Shape of the Idea

Braid reads your sources, and an AI drafts a domain model from them. The model is typed by an ontology, so it reads as a domain rather than a call graph. The default ontology is Domain-Driven Design, so a node is a bounded context, an aggregate, a command, or a rule, named in the ubiquitous language of the product.

A domain model is less an extraction than an agreement. The same code admits more than one honest reading, and the one that counts is the one the domain's owners will stand behind. Some of it is never in the source at all, like why a rule exists, and only a person can supply that. So the AI never has the final say. Every change arrives as a proposal a person approves before it lands, and when the AI is unsure how an expert sees the domain, it asks rather than guesses. As the code changes, Braid reacts and feeds the diff back as a fresh proposal, so the model keeps pace instead of going stale.

The result is one artifact an engineer, a PM, and a QA can all point at, traced back to the source it was drawn from.

A Real Run, From Code Alone

The strongest version of the claim is the hardest one. Give Braid a codebase with no docs at all, and see whether it produces something a person would recognize as their domain.

So in Studio I created a workspace, pointed it at conciergent, a service of mine that gives MCP tools a chat face on Slack, LINE, and Discord, and gave it no intent documents at all. Only the code.

Braid splits the codebase into business units first, models each one, then reconciles the overlaps into a single graph. The scan found eight units on this repo, and the reconciled model has 120 nodes and 159 edges across five bounded contexts, with no failed unit.

The full example is committed at examples/conciergent.

What Braid Actually Does

Three things, each of which showed up in that run.

1. A Model in the Language of the Domain

The nodes are not classes. They are the concepts the product is about, described in plain language. Here is one aggregate from the run, its description quoted directly with the trailing state diagram left out:

Pending Approval. A sensitive action held back until the user says yes. When the assistant wants to use something the tool provider marked destructive, the action does not run: the work already in flight is set aside and the user is shown a confirmation with Confirm and Cancel.

Rules that always hold:

At most one confirmation waits per conversation, and picking it up consumes it, so the same held work can never run twice.

The confirmation ages out on its own, and held work that can no longer be read counts as expired.

One answer decides every action held in that pause.

Nothing in there is Domain-Driven Design jargon, and nothing is a code identifier. It reads like a domain expert explaining the rule, because that register is exactly what the ontology asks the model to write in. A PM can read it, a QA engineer can turn each rule that always holds into a test, and an engineer can check it against the code.

2. The AI Drafts, a Person Decides

An AI-built model will not always match how each expert sees the domain. So Braid does not let the AI write to the model directly. Every change is a proposal, reviewed before it lands, and every disagreement is settled by a person rather than by the model's confidence.

When the model runs into something genuinely ambiguous, it does not paper over it. It raises a question and waits for an answer, and that answer becomes part of the model. The loop is the point. The AI does the drafting, the people who own the domain do the deciding, and neither one is doing the other's job.

Answering a clarification, running clarify to turn it into a proposal, then reviewing the diff and applying it. The model gains the node the moment it lands.

3. Every Claim Points Back at Its Source

Each node carries a reference to the source it was drawn from, down to the file and line for a code source. A claim in the model can be traced back to the exact place it came from, rather than taken on trust. When you disagree with a node, you can open the evidence and see what the AI was reading when it wrote it.

A View You Can Hand a PM or QA, Projected From the Model

The model is the one artifact everything else derives from. Everything else is a view of it, a read-only projection you regenerate rather than a second copy that drifts. A document is one such view, rendered a file per bounded context or just the one you point it at, in the same plain language as the model, for whoever has to understand it without reading code. Because it all comes from one model, a view can be cut to what a team needs, scoped wider or narrower, aimed at a different reader, or shaped as something other than prose.

Here is how the doc it generated for the Conversation Turn Lifecycle context opens, unedited:

Conversation Turn Lifecycle

A person sends one message in a chat app and expects one useful answer back. Answering can detour through a sign-in, a confirmation the user has to tap, or a conversation so long the assistant can no longer hold all of it. This subsystem owns that single round trip, from an arriving message to a sent reply and an up-to-date conversation memory.

It goes on with a glossary of the terms the subsystem uses, the people it serves, each use case with the rules that always hold, and a lifecycle diagram. None of it is in code terms, and a draft banner sits up top because every node is still unreviewed. It closes with the exact nodes it was drawn from:

Source nodes: ctx.conversationTurn, actor.chatUser, agg.turn, cmd.runTurn, evt.replySent, rule.oneReplyPerTurn, and twenty-five more.

Regenerate it after the model changes and it changes with the model.

How It Compares

I did the homework so you do not have to. Braid sits next to three kinds of tool teams reach for today, each solving part of this problem.

	Braid	Team Docs	AI Repo Wiki	Self-Writing Wiki
A Typed Graph Model	Yes, Nodes and Edges	No, Pages	Partly, Diagrams	Partly, Linked Pages
Speaks the Domain	Yes	Yes	No, Code-Facing	Partly, Freeform
Keeps Pace With the Source	Yes, Reacts to Source	No, Drifts	Yes, Regenerates	Yes, Compounds
A PM or QA Can Read It	Yes	Yes	Partly	Yes
One Reviewed Source of Truth	Yes, Human-Gated	No, Hand-Maintained	No, Auto-Generated	No, Self-Written
Traceable to the Source	Yes, Per Node	No	Partly, Links to Code	Weak
Examples	—	Notion, Confluence	DeepWiki	LLMwiki

Reading guide:

Team docs in Notion or Confluence are the simplest option if you can live with prose that drifts.
AI repo wiki like DeepWiki gives the quickest read on an unfamiliar repo, but it documents the code rather than the business, and nobody reviews what it writes.
Self-writing wiki like LLMwiki maintains itself and resolves contradictions on its own, but that is also the risk, the AI has the final say and you are out of the loop.
Braid is for one reviewed, traceable model of the domain that engineers, PMs, and QA can all read and that keeps pace as the code moves.

What Is and Is Not There Yet

Braid is a young project, and I would rather be precise than oversell it. Everything above works today. What does not, in case it would block you:

Ontologies beyond DDD. The ontology is a plugin and the framework does not assume DDD, but DDD is the only one shipped so far.
Agents beyond a coding agent. The model is built by a coding agent today. A general chat surface over the model is on the roadmap, not in the box.
Proof at scale. The runs so far are modest repos like the one above. Whether the model stays coherent on a large, sprawling codebase is unproven, and it is genuinely hard to validate.

If one of these is what stands between you and trying it, an issue with the shape of your problem helps more than my guesses.

Wrapping Up

This is a personal side project, built to settle an argument I have watched teams have for years. If the drift between what shipped and what the team meant sounds like your problem, give it a run and open an issue with what is missing.

Repository: github.com/mroops0111/braid
The example above: examples/conciergent

Shape a Messy API into Clean MCP Tools with JSONata

MrOops — Thu, 06 Aug 2026 18:35:20 +0000

A raw OpenAPI operation rarely makes a good MCP tool. It exposes parameters the model should never set, speaks in cryptic API values, and hands back a bloated response envelope, so the model either misuses the call or drowns in the payload. openapi-mcp-gateway fixes this with shaping. From one YAML block next to the operation, you declare the friendly input with params and rewrite the request and response with JSONata, without forking the spec. It does four things.

You decide the input. Hide or fix the parameters the model should not choose, like a pinned project scope or pagination, expose only the friendly ones, and restrict values with enum. It is enforced, so anything you did not expose cannot be set, and an out-of-range value is rejected before the call.
It speaks the model's language. Friendly names and enums map onto the raw API values (popular becomes popularity.desc), so the model never invents a sort_by string or a filter DSL.
You shape the output. Trim the envelope down to the fields that matter (less context), and rename or flatten them (vote_average becomes rating) so the result is easy for the model to use.
It stays declarative. No wrapper service to write and deploy, and the model-facing tool holds steady when the upstream spec shifts.

Quickstart

uv add openapi-mcp-gateway

The TMDB example behind everything below ships in the repo. From a checkout, point it at your token and it serves the two shaped tools:

export TMDB_TOKEN="<your v4 read token>"
uv run openapi-mcp-gateway --config examples/movie-shaping.yml

Tool shaping is available in openapi-mcp-gateway 0.6.0+, Python 3.11+.

The Shape of a Tool

Three keys under x-mcp-integration.tool do the work.

params and strategy declare what the model sees.
request is a JSONata expression that maps the friendly arguments onto the upstream request.
response is a JSONata expression that reshapes the upstream body before it reaches the client.

params entries are plain JSON Schema fragments (type, enum, default, description). strategy says how they relate to the spec. replace makes them the whole input schema and drops the spec's parameters, and merge layers onto the spec and keeps the rest.

A Real Example: The Movie Database

TMDB's /discover/movie is a good punching bag. It takes sort_by (values like popularity.desc), include_adult, language, and page, and returns a large envelope. Here is the whole friendly tool.

operations:
  discover_movies:
    tool:
      strategy: replace
      params:
        sort:
          type: string
          enum: [popular, top_rated, newest]
          default: popular
        page:
          type: integer
          default: 1
      request: |
        {
          "sort_by": $lookup(
            {"popular": "popularity.desc", "top_rated": "vote_average.desc", "newest": "primary_release_date.desc"},
            sort
          ),
          "page": page,
          "include_adult": false,
          "language": "en-US"
        }
      response: |
        [results.{
          "title": title,
          "overview": overview,
          "release_date": release_date,
          "rating": vote_average
        }]

The model sees exactly two inputs, sort and page. Everything else is handled for it.

$lookup translates the friendly popular into the raw popularity.desc.
include_adult and language are injected as constants the model never sees.
The response keeps four fields per movie and renames vote_average to rating.

A call with no arguments goes out as sort_by=popularity.desc&page=1&include_adult=false&language=en-US, and comes back as a short list of {title, overview, release_date, rating}.

Why JSONata

The response side looks like a query, and a query language could do it. The request side cannot. Building sort_by from a lookup table, injecting constants, or fanning one friendly query out into the repeated f[] / op[] / v[] parameters of a filter DSL is construction, not selection. JMESPath and JSONPath query, they do not build. JSONata does both, so one engine covers request and response.

Two idioms carry most of the weight.

$lookup(table, key) maps a friendly enum onto the raw API value.
[ ... ] forces a list. A projection like results.{...} unwraps to a single object when only one item matches, so the array constructor keeps it a list every time.

To pass most arguments straight through and change only a few, merge them with $merge([$, { ... }]), where $ is the whole input.

merge vs replace

replace is for a full reshape. You hide the raw API entirely and declare a clean interface, as above. merge is for a light touch on an API that is already close.

tool:
  strategy: merge
  params:
    internal_flag: { hidden: true }
    per_page: { default: 30 }

Here the spec's other parameters stay visible, internal_flag is hidden, and per_page gains a default. Naming a parameter the spec does not define is a startup error, so a typo fails loudly instead of silently dropping a field.

Loud Failures

Both expressions compile at startup, so a broken JSONata takes the server down on boot with a clear message rather than on the first call. A runtime evaluation failure comes back as an isError result that names the side that broke, request or response.

FAQ

Does shaping work in dynamic exposure mode?

Yes. A dynamically exposed operation gets the same shaped input schema, request, and response as the static path. The one thing dynamic mode drops is per-operation tool annotations.

Wrapping Up

One OpenAPI operation no longer has to mean one bad tool. params and strategy shape what the model sees, and request and response shape the bytes on the wire, all from one YAML block next to the operation. If you try it on a real API, I would love to hear which operations were the worst to tame.

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

I Built Conciergent: Give Your MCP Tools a Slack, LINE, or Discord Chat Face, With Real In-Chat OAuth

MrOops — Tue, 14 Jul 2026 10:36:20 +0000

A while back I built openapi-mcp-gateway, which turns any OpenAPI spec into an MCP server. That solved the supply side. But the people who most wanted those tools, product folks, support staff, ops, were never going to install Claude Desktop and paste a server URL into a config file. They live in Slack and LINE.

The real work was putting a chat face on those tools, one a non-technical person can just talk to. Once you try it, three things stop being optional very fast.

You need per-user auth that happens inside the chat, because you cannot send someone to a JSON config to complete an OAuth flow, and you certainly cannot let the whole team act as one shared service account. You need a confirmation step before anything destructive runs, because an LLM with write access to a real API will eventually try to do the wrong thing confidently. And you need replies that render natively on each platform, because a wall of Markdown that looks fine in one client is broken in the next.

By the time all three worked, I had Conciergent.

It connects to any Model Context Protocol server (or an OpenAPI spec directly) and turns it into a Slack, LINE, or Discord bot that can actually do things. Per-user OAuth is handled inside the conversation, destructive tools pause behind an approval card, and the agent emits one structured reply that each surface renders on its own. You point it at a YAML and it runs.

Who it is for matters as much as what it does. This is a bot you stand up for your users, each signing in as themselves, not a personal assistant you run for yourself.

Try It

uv add "conciergent[gateway]"
uv run conciergent init      # writes an annotated manifest.yml

The scaffolded manifest.yml is a full config with the surface and store already wired up. Point the agent at an MCP server, or drop in an OpenAPI spec, set your Slack, LINE, or Discord credentials as env vars, and:

uv run conciergent run

The fastest end-to-end path is the bundled Docker compose, which brings up Redis, Postgres, and the app together from one of the example configs:

cp examples/openapi-chat.yml manifest.yml
docker compose up

Python 3.12+. Three model providers ship in the box (OpenAI, Google Gemini, Anthropic Claude). Set agent.model to a provider:model string and export that provider's key.

What Conciergent Actually Does

Three things, each shown in config.

1. Any MCP Server, or an OpenAPI Spec Directly

Most useful bots touch more than one thing. Point the agent at any MCP server URL:

# manifest.yml
agent:
  model: openai:gpt-4o-mini
  system_prompt: |
    You are a helpful assistant. Use your tools to answer the user's requests.
  mcp_servers:
    - http://localhost:9000/mcp
    - https://another-server.example.com/mcp

And if what you have is a REST API rather than an MCP server, you do not need to run a second process for it. Add the gateway extra and Conciergent embeds openapi-mcp-gateway in-process, so a spec becomes MCP tools right there:

gateway:
  enabled: true
  specs:
    - name: petstore
      spec: https://petstore3.swagger.io/api/v3/openapi.json
      base_url: https://petstore3.swagger.io/api/v3
    - name: internal
      spec: ./internal-api.json

Each spec is served at /{name}/mcp and wired into the agent for you, alongside anything already in agent.mcp_servers. A spec entry mirrors openapi-mcp-gateway's per-server config, so a large API can use exposure: dynamic (the agent sees three meta-tools instead of one per endpoint), a policy filter to keep endpoints away from the model, or auth.

2. In-Chat OAuth (The Constraint That Drove The Design)

This is the part that makes a chat bot different from an MCP client on your laptop. When a tool needs authorization, there is no config file to edit and no desktop app to bounce through. The user is in a Slack, LINE, or Discord DM, and the authorization has to happen right there.

So Conciergent runs the whole OAuth handoff inside the conversation. The first time a tool needs a token, the bot posts the authorization link into the chat. The user taps it, approves, and comes back to the same DM. Conciergent stores the token and refreshes it from then on, per user. Nobody leaves the conversation, and nobody shares one team-wide credential.

The same handoff covers an oauth2 spec behind the embedded gateway, so each user authorizes their own upstream account before its tools run. And because the flow is time-bounded, a slow authorization expires cleanly instead of hanging the request.

Tokens persist in Postgres, so a redeploy does not sign everyone out. Chat history lives only in Redis, kept just long enough for context before it expires on its own, along with the other transient state (approvals, the pending handoff). Nothing a user says is retained past that window.

3. An Approval Gate, and One Reply That Renders Everywhere

Two problems, one design.

Human-in-the-loop. Any tool the MCP server marks destructive pauses behind a Confirm / Cancel card before it runs. The model proposes the action, and the human commits it. A pending approval has its own TTL, so an ignored card does not sit forever holding a write open.

Surface-agnostic replies. The agent never speaks Slack, LINE, or Discord. It emits one of three shapes, and each surface renders it natively:

str for plain text.
Card for a header, text sections, an optional hero image, a footnote, link buttons, and suggestion quick-replies.
Carousel for a small set of option cards the user picks between.

A suggestion is the interactive primitive. Tapping one posts its prompt back to the agent as if the user had typed it. The field descriptions on these models are the agent's structured-output schema, so the model fills them in directly and the same reply object renders correctly on Slack, LINE, and Discord.

UI text (buttons, prompts, greetings) is not hardcoded either. It lives in a locale catalog, picked from each user's platform language, so the bot answers people in their own language with no per-message translation calls.

How It Compares

The question that sorts this field is not which agent has the most features, but who the bot is for. Conciergent is built for a service provider who wants to give their own users a bot on the Slack, LINE, or Discord those users already have. Most of the projects it gets compared to are built for someone else, so they make different trade-offs. Two groups come up the most:

Personal assistants like Hermes Agent and OpenClaw. You run one for yourself and reach it from any chat app. They do far more than Conciergent (voice, memory, self-improving skills, dozens of channels), but each install serves a single owner with a single set of credentials, so there is no notion of separate end-users.
Self-hosted AI platforms like Dify, Open WebUI, and LibreChat. They overlap the most, with multi-tenant deployments, per-user OAuth, native MCP, and heavy maintenance. But your users reach them in the platform's own web app. Getting onto Slack or Discord means a relay that pipes that web-app chat into the DM, text-first, with no native cards and no per-user OAuth in the conversation.

	Conciergent	Personal assistants	Self-hosted AI platforms
Built for	Your users	Just you	Your users
Surface	Their Slack / LINE / Discord	20+ chat apps	Its own web app
Separate end-users	Yes	No	In web app
Per-user OAuth	Yes, in chat	No	Yes, in its web app
Native cards and carousels	Yes, per surface	Text-first	Web app only
Approval gate	Yes	Yes	Partial
MCP and OpenAPI to tools	Both	MCP only	Both

The assistants that reach these surfaces run for a single owner, and the multi-tenant platforms stay in a web app. Neither puts a per-user bot with native replies in the chat itself.

It fits three situations in particular:

Internal tools for non-technical teammates. Support, ops, finance. They will never open an MCP config, but they will DM a bot. Point Conciergent at your internal MCP server (or spec) and they talk to it.
Anything where actions must happen as the actual user. Approving a request, moving a record, closing a ticket on someone's behalf, where the upstream audit log has to show the human. The in-chat per-user OAuth handles that end to end.
A REST API you want to demo as a chatbot fast. Enable the gateway, drop in the spec, and you have a Slack, LINE, or Discord bot over it with no second server to run.

What Is And Is Not There Yet

Everything above ships today.

From here, the main line of work is more surfaces. Each one is a single class behind the surface contract, with the runtime and agent unchanged, so the list keeps growing without a rewrite. Telegram and Teams are next. If your platform or use case is not there yet, open an issue with the shape of your problem. Concrete use cases drive the design more than my guesses.

Closing

Conciergent is the companion to openapi-mcp-gateway. The gateway turns a REST API into MCP tools, and Conciergent gives those tools a chat face. Together they take one or more OpenAPI specs all the way to a bot your users can talk to. Like the gateway, this is a personal open-source side project. Sharing it here in case the situations above sound like yours.

Repository: github.com/mroops0111/conciergent
Companion Project: github.com/mroops0111/openapi-mcp-gateway

Expose a Huge OpenAPI Spec as MCP Tools and Resources

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

A 1,000-endpoint OpenAPI spec should not ship 1,000 tool schemas at connect time, and a read-only GET is often a better MCP resource than a tool. openapi-mcp-gateway fronts huge specs so they do not blow the context window, promotes eligible GETs to resources, and keeps the auth in between spec-compliant. Four pieces:

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

Quickstart

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:
        resource:
          name: pet
          uri_template: petstore://v2/pet/{petId}
      getInventory:
        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.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. The gateway handles both.

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.tool:

x-mcp-integration:
  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.

FAQ

Can I use dynamic exposure and resources together?

No. Dynamic exposure surfaces every operation uniformly behind the three meta-tools, so resource promotion and any x-mcp-integration.resource opt-ins are skipped, with a warning at startup. Pick exposure: dynamic for a huge spec, or mode: auto for resource partitioning, per server.

Wrapping Up

A huge spec does not have to flood the context window, and a read-only GET does not have to be a tool. exposure: dynamic and mode: auto handle those, and the auth in between stays spec-compliant. If you try it, open an issue with what broke or felt awkward.

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

Turn an OpenAPI Spec into an MCP Server in Python

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.

You point it at a YAML and it runs.

Quickstart

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.

FAQ

Can I run several mounted servers over stdio?

No. stdio serves a single server. The multi-spec setup, where each API sits at its own mount path, needs streamable HTTP or SSE.

Does it pick up spec changes without a restart?

No. The spec is read at startup and the tool list stays fixed while the process runs. Restart to regenerate from the changed spec.

Wrapping Up

This is a personal side project, shaped by the kind of agent flows I think about from my dayjob (a B2B e-signature API) but independent of it. If any of the situations above sound like yours, give it a run and open an issue with what is missing.

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

DEV Community: MrOops

Turn a Codebase into a Domain Model Your PM and QA Can Read

The Shape of the Idea

A Real Run, From Code Alone

What Braid Actually Does

1. A Model in the Language of the Domain

2. The AI Drafts, a Person Decides

3. Every Claim Points Back at Its Source

A View You Can Hand a PM or QA, Projected From the Model

Conversation Turn Lifecycle

How It Compares

What Is and Is Not There Yet

Wrapping Up

Shape a Messy API into Clean MCP Tools with JSONata

Quickstart

The Shape of a Tool

A Real Example: The Movie Database

Why JSONata

merge vs replace

Loud Failures

FAQ

Does shaping work in dynamic exposure mode?

Wrapping Up

I Built Conciergent: Give Your MCP Tools a Slack, LINE, or Discord Chat Face, With Real In-Chat OAuth

Try It

What Conciergent Actually Does

1. Any MCP Server, or an OpenAPI Spec Directly

2. In-Chat OAuth (The Constraint That Drove The Design)

3. An Approval Gate, and One Reply That Renders Everywhere

How It Compares

What Is And Is Not There Yet

Closing

Expose a Huge OpenAPI Spec as MCP Tools and Resources

Quickstart

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

FAQ

Can I use dynamic exposure and resources together?

Wrapping Up

Turn an OpenAPI Spec into an MCP Server in Python

Quickstart

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

FAQ

Can I run several mounted servers over stdio?

Does it pick up spec changes without a restart?

Wrapping Up

3. FastAPI-Native `@mcp_tool`