--- title: "Why MCP has no openapi.json" date: 2026-11-19 thumbnail: "static/img/blog/posts/2026-11/mcp-server-manager-og.jpg" thumbnail_alt: "MCP Server Manager in MEGA OS showing a Cloudflare Worker wired to Workers AI, a D1 database and a KV namespace" tags: - "Agentic Engineering" - "MCP" # Optional. Used for search results and link previews; defaults to the site description. description: "MCP Tools are meant to change at runtime, so there is no static API spec for them. Here is what that means for agents, and how I handle it." hacker_news_post: https://news.ycombinator.com/item?id=50561114 --- Before we start, a short clarification. I'm not criticizing MCP. I am myself a regular user of it. For a couple of months now, I have been connecting my harness to multiple MCP Servers, and in the last few weeks I've also built a few myself. However, there is an important caveat to consider when dealing with MCP Servers and MCP Tools. Let's start with the basics. An Application Programming Interface (API) is a set of rules or protocols allowing different applications to communicate with each other and exchange data. So? An MCP Server exposes some MCP Tools, and those are APIs, right? Yes, but they are also more than just APIs. ![While completing challenges for the [mega.dev](https://mega.dev/) course, I've decided to build myself an MCP Server management system. It's a part of a larger system of mine, called *MEGA OS*. It lets you quickly spawn a new MCP Server on Cloudflare, and expose it under a public URL. OAuth is backed by Cloudflare's KV namespace, MCP Tools data is kept in D1 database, Workers are used for MCP Server business logic, and Workers AI for speech-to-text.](static/video/blog/posts/2026-11/mcp-manager.mp4) I tend to think of MCP Tools as conversational units. If you think about the fact that an MCP Tool returns its responses to an AI Agent, the way a human participant would, you can think of an MCP Tool simply as another chat participant. From the language model's point of view, a tool call result and a user message are nearly the same thing - both are just text that came from outside the model. [In Anthropic's Messages API, a tool result is literally sent inside a `user` message](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls#handling-results-from-client-tools). The one real difference is trust: models are trained to follow instructions from the user, but to treat instructions found in tool results as data. That is one of the main defenses against prompt injection. And it makes sense - if a tool talks like a chat participant, it can also mislead like one. In principle, MCP extends the language model's context with some external data. ![MCP Server providing contents of the D1 database table in one of its Tools](static/img/blog/posts/2026-11/mcp-server-database.png) But if you try to give your MCP Tool (or Server) a static, published specification, the MCP maintainers seem to say you shouldn't do that (more below). Why do I need a specification? If I have an API and want to give it to my application, then my application needs to know the input and output schemas. Nowadays, mature HTTP REST APIs implement that with OpenAPI documents. "Okay," - you say - "the MCP Tool schema spec is provided by the `tools/list` JSON-RPC method, and that is how you get the JSON schemas, right?" Right, except that both the spec and its maintainers imply that those schemas are dynamic in nature. I don't mean this as a negative thing. It fits how agents work: they act, look at the result, draw a conclusion and act again. An agent that reads the tools as they are right now, instead of assuming what they used to be, keeps that loop grounded in what it actually sees. ![Example Input Schema of an MCP Tool read from `tools/list` JSON-RPC method](static/img/blog/posts/2026-11/example-mcp-tool-input-schema.png) But what does "dynamic nature" mean? There is no equivalent of an OpenAPI Schema for MCP Server Tools - a schema that maps 1:1 to the API, and shared publicly. MCP **does have** the schema content, but has no standard way to publish it as a file anyone can fetch. MCP has per-tool schemas. Each tool in a `tools/list` reply carries an `inputSchema` and optionally an `outputSchema`. But MCP doesn't have any standard document format for "this server's tools", like `openapi.json`. Nor is there a standard public place to put one. The Server Card leaves tools out on purpose, and the registry's `server.json` has no field for them either. The tools list can change over time. The server sends `notifications/tools/list_changed` to clients that subscribed to it. Since the [`2026-07-28` revision](https://modelcontextprotocol.io/specification/2026-07-28/changelog), every list must say how long a client may cache it (`ttlMs`, `cacheScope`, [SEP-2549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549)). That is the replacement for a static file. **The MCP maintainers keep tools out of public files**: they removed them from the Server Card ([PR #2336](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2336)), whose [spec](https://github.com/modelcontextprotocol/ext-server-card) now says it "intentionally omits primitive listings". The registry holds back too, on proposals to describe a server's tools in `server.json`: one has been open since 2025 ([#82](https://github.com/modelcontextprotocol/registry/issues/82)), and another was folded into it in October 2026 without adopting any format, because dynamic and auth-dependent tools still need a design decision ([#1720](https://github.com/modelcontextprotocol/registry/issues/1720)). The reason: a static copy goes stale and misleads. So MCP Tools are meant to be non-static. Remember that, and make use of it, when designing your agentic workflows. Security people will rightly point out that a tool list changing at runtime is exactly how "rug pull" and tool-poisoning attacks work, which is why some of them want every tool pinned and fingerprinted. Both can be true: pin and review the tools you have seen, but design your agent to expect that the list will change. In my own MCP Servers, I deal with it by exposing the `tools/list` method without authentication, and it always returns the same complete list. That way, the client code can verify the tool definitions, including descriptions, against hashes of the versions that were reviewed, before the first use and before every later use too. The list can change between releases, but never depends on who's asking. Leaving it without authentication is acceptable in my case, because I am building an environment for observability of MCP Servers, where the tool definitions are one of the inspected elements. An API is a versioned contract, frozen at the moment you publish it. GraphQL comes close with its introspection, but its schema is read by client code written in advance. An MCP Tool's definition is read by the model itself, every time it decides what to do. An MCP Server is closer to a living organism: its tools appear, change and disappear, and the only way to know what it looks like right now is to talk to it - just like with any other participant of the conversation.