You don't know what MCP servers do. Not until you connect and run the tools/list method. And MCP servers are everywhere now. Every AI product wants one, every API team is being asked to build one, and the ecosystem is moving faster than you can keep up with. New servers show up every day, some official, some hacked together over a weekend, all exposing tools, resources, and prompts that AI agents are supposed to know how to use. And there's no way to know what they do until you connect. There's no document you can just open and read, no machine-readable reference you can point your tools at, nothing you can check before deciding whether to use an MCP server. Annoying, right? Stay with me to see how this can change.
This article is brought to you with the help of our supporter, Scalar.
Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth.
Something as simple as an OpenAPI document can give you knowledge about anything related to an API: operations, parameters, authorization, even support contact in case you need it. You don't have to connect to the API to know what it does. Think, for a second, how strange that would be. But that's exactly what happens with MCP. The protocol only tells you how to ask a server what it does while it's running. There's no way to know what an MCP server offers before you turn it on. This isn't just inconvenient. It also makes a few things difficult. Let's start with documentation. Someone has to write it, and today that means running the server, poking at it, and writing down what they find by hand. Nobody can design a server on paper before building it, because there's nothing to design against. Every software that wants to inspect a server has to build its own way of connecting and asking, because there's no shared file to read instead. And worst of all, there's no way to check that a server actually does what it claims. You just have to run it and trust it.
So, what have people done about it? They’ve been dealing with this problem in different ways for a while now. Some teams have been writing internal docs by hand. Some wrap their MCP servers with OpenAPI-style descriptions attached on the side. Some write one-off scripts that connect to a server, dump whatever it returns, and pass that around as documentation. A few just keep a spreadsheet of every tool and resource a server exposes, updated by hand. None of these are standardized, of course. That’s why they don’t work well across tools. And adoption is limited, making them almost impossible to survive when a team changes. Every one of these workarounds solves the same problem in a slightly different way. What’s missing isn’t more effort. It’s a format everyone can agree on. A real standard.
Is there a real fix, though? One project is trying: mcpdesc. Their pitch is simple: OpenAPI, but for MCP. Instead of connecting to a server to find out what it does, you write (or generate) a static file that says exactly what the MCP server offers: its tools, resources, prompts, transports, and security. You get all the information in one place, in YAML or JSON. Here’s what a minimal mcpdesc document looks like:
Here's what this description looks like when rendered by the Live MCP Description Editor. Pretty neat!
That’s it. You don’t need a running MCP server just to know what this thing does. And if you already have a server running, you don’t even have to write the description by hand (a CLI called mcpcontract can connect to a live server and dump a full mcpdesc document). Once you have the file, things get easier: you can generate real documentation straight from it instead of writing it by hand, lint it, validate it, and diff two versions to understand what changed. You can check it into your CI/CD pipeline like any other artifact, compare what a server claims against what it actually does, and design a server on paper first, or mock it with mcpmock, and only then write the code. You can, essentially, do anything you can do with an OpenAPI document. But for an MCP server.
So what does it actually take you to get there? Right now, mcpdesc is a young, single-vendor project. The spec is version 0.7.0 and marked Draft. The only credited maintainer is Stève Sfartz, a Principal Architect at Cisco, and every tool that reads or writes the format (mcpcontract, mcpmock, the editor) comes from the same place: Cisco’s open source org. It was announced about a month ago. Nobody outside that project has adopted it yet. Also, something to take into account is that MCP’s own Server Cards proposal, SEP-2127, looked at describing a server’s tools and prompts and explicitly set it aside for now. That means they could still absorb it at a later stage, making mcpdesc redundant if both standards ever compete. Even the ability to inspect a running MCP server and generate a description has a real limit. Sfartz told me that “live discovery using the dump command is not sufficient for MCP servers that expose different tools based on user permissions,” so for those servers you’re better off generating the description straight from the code than trusting a live dump (check my full interview with Sfartz further down if you want all the details). If you start using it today, you’re adding one more file to keep in sync with reality, on a spec that could still change shape, built by a maintainer who himself says mcpdesc “is not necessarily” the format that ends up standardized. Especially if the folks at Anthropic and the other MCP maintainers decide to build it into the protocol themselves.
Why so much negativity? I’m just being realistic so you know what you’re getting. Here’s the actual choice. You can keep living without a description, which costs you nothing today but leaves you unable to write real docs, test conformance, or design servers ahead of time. Or you can start writing mcpdesc files now, knowing it’s early and it’s a single company’s bet. I’d try it. The problem is real, and writing mcpdesc documents sounds easy. But I wouldn’t use it in production yet. There’s still too much ambiguity at this point. But you’re not me, so take your time and make your choice.
Here’s the full interview with Stève Sfartz from Cisco. Some parts have been edited for improved readability.
Bruno Pedro: Why do we need a separate document to describe what an MCP server does, when the protocol already lets you inspect it live?
Stève Sfartz: We identified the need for a static document while publishing documentation for the very first MCP servers that came in at DevNet. This blog post from August 4, 2026 provides some details: Beyond the Protocol: Applying API Engineering Practices to MCP Servers. In summary, these are the questions we needed to have answers for to publish documentation, questions that the MCP protocol alone could not address:
How do we document MCP servers consistently?
How do we review them before publication?
How do we compare one release with the next?
How do we detect major changes across releases?
And beyond, I am responsible for quality and consistency across the whole portfolio. I needed these questions answered:
How do we keep engineering teams, documentation teams, and developer-facing portals aligned? (governance)
How do we ensure consistency within a product and across products? (compliance)
That is why we started creating a description document for MCP servers.
BP: mcpdesc is a Cisco project with you as its single credited maintainer, right?
SF: The initiative started at DevNet, where I am the lead maintainer. The tooling is used internally at Cisco for publishing and internal workflows. The need for such a format was identified in the spring of 2025. I could not identify any similar initiative in the community, so, as the lead architect, I built the first version of mcpdesc. That happened between July and August 2025 for DevNet publishing purposes. After that, I built the mcpdesc tooling between September and December 2025, first focusing on the mcpcontract dump capability, and then the mcpcontract changelog. Other tools came from internal teams building MCP servers as needs emerged. For instance, mcpmock, one of those tools, is interesting to drive a design-first approach to MCP servers. And mcptest has received very little feedback so far.
The MCP Server Card specifications, SEP-2127, originally targeted documenting capabilities (tools, prompts, resources). Our goal was to switch the mcpcontract tool to use the server card format once standardized. But SEP-2127 finally focused on discovery only and omitted capabilities, i.e., primitives, as mentioned in the draft, leaving this aspect to future work. That’s when we decided to publish the MCP description (mcpdesc) externally, and contribute with our internal toolset to the community. I then created mcpdesc.org to start the conversation and promote the need for a standardized format. However, mcpdesc is not necessarily that format. We will be evolving it as needs arise, while engaging with the MCP specifications maintainers to create an official standard.
BP: Why should anyone outside Cisco trust it enough to build on it?
SF: Well, if a format such as the MCP description existed, we would have built on it rather than created a new one. We shipped the toolset at Cisco Open with an Apache license, and are now working on v0.8 of the format to support MCP 2026-07-28. We also created mcpdesc.org as an open initiative to evolve the format as needed. I’d encourage everyone to test the toolset and the mcpdesc format with their own MCP servers and contribute to improve and extend the toolset. The future will say if there is enough traction for a standardized description format. Best case, it’s a yes, and the mcpdesc format (or a pretty similar one) is standardized. Worst case, it’s a no, and the mcpdesc format will still exist for individuals that see benefits in using it.
BP: If someone wants to try mcpdesc on a real server right now, what’s the first thing they should do, and where are they likely to get stuck?
SF: The mcpdesc.org portal is very recent and being actively worked on. I’d suggest testing the format using the live editor. There are specification examples included, and anyone familiar with OpenAPI and its tool ecosystem should ramp up in minutes, if not seconds, as the format and tools are inspired by OpenAPI. Indeed, mcpdesc targets the exact same needs as OpenAPI does for REST APIs, but applied to MCP servers. There is no rocket science here, simply applying API engineering best practices to MCP. MCP is very different from a REST or Web API. The protocol is very rich, which offers many benefits and features related to dynamic discovery and agent interactions, and the Anthropic team and MCP maintainers are doing a great job. The tools around MCP are still being built, and it’s time for everyone to contribute to the success of MCP. I hope mcpdesc (or a similar format) will help the tooling ecosystem by offering a standardized way to describe MCP servers so that all engineering quality, compliance, and governance activities can be organized based on a standardized format. After trying the mcpdesc format live in the editor, I’d recommend creating a dump of an existing server using the mcpcontract CLI with the dump command. Dumps are pretty straightforward to create for stdio and HTTP servers. For servers using OAuth, there can be some challenges with some OAuth implementations based on the discovery sequences. Using the --verbose mode should help you diagnose any issue. One note: live discovery using the dump command is not sufficient for MCP servers that expose different tools based on user permissions. In such situations, generating an MCP description document from the actual code (using comments or annotations) would be a better approach.
Thanks for reading The API Changelog!
Please consider subscribing to receive new posts and support our work.
Not convinced yet? Get to know why we’re considered “the most important API newsletter out there.”
Comments
Nothing yet. Say the first thing.
Sign in to join the conversation.