Your MCP server needs documentation, and it is not your API docs

There is an open question in the MCP ecosystem right now about whether servers should have a static description format of their own, something that plays the role OpenAPI plays for HTTP APIs. Today there is not one. A server describes its tools at runtime, over the protocol, to whatever client connected.

Which means the only thing a human evaluating your server can read is whatever you wrote down. And most teams write a config snippet and stop.

That gap matters more than it looks, because the person deciding whether to connect your server is not the agent. It is a developer weighing whether to point an autonomous process at their production API, and they need to answer questions the protocol will not answer for them until after they have already connected.

The questions your page has to answer

What does connecting this actually let an agent do? Not the tool list. The capability. Can it read my data, write to it, spend money, message my customers? A developer should be able to answer this before installing anything.

Which of the tools have side effects? This is the one people most want and least often find. Split the tool list in two: the ones that read, and the ones that change something. A reader scanning for risk is scanning for that second list.

What credentials does it need and what can they reach? Which environment variables, what scopes, and whether the token you are asking for is the same one their normal API client uses. If a narrower credential works, say so, because most people will otherwise paste in the broadest key they have.

Which environment does it hit? If there is a base URL setting, it belongs near the top, not in a configuration table at the bottom. The default should be stated plainly, because someone will connect this to production on the first try if you let them.

How do I limit it? If an integrator can exclude tools, restrict scopes or point it at staging, that is a headline feature and not a footnote. It is the thing that turns "this looks risky" into "I can try this safely".

The config snippet is necessary and not sufficient

Every MCP server page has this, and it should:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["@acme/mcp", "--project-id", "YOUR_PROJECT_ID"]
    }
  }
}

Three things make the difference between a snippet that works and one that generates support questions.

Say where the file lives, per client. Claude Desktop, Cursor, VS Code and Claude Code all read different paths. Listing the JSON without the path is the most common omission, and the answer differs by operating system too.

Say that the config is read at startup. Restarting the client after editing is the single most common reason a correct config appears not to work.

Show how to verify it connected. One sentence: what the user should see in their client when the server is live. Without it, a silent failure and a working setup look identical.

Document the transports as a choice, not a list

Most servers support a local process over stdio and some form of hosted transport. These are not equivalent options and the docs usually present them as though they are.

stdio means the client starts the process on the developer's own machine. No ports, no hosting, no network exposure, credentials stay local. It is the right default for nearly everyone and it should be presented as the default rather than as one of two.

A hosted transport exists for teams that would rather run one instance than have everyone configure their own. That is a real need and it comes with a real consequence: the credentials now live on a server somebody has to secure, and the connection is reachable over a network. Saying which is which is more useful than documenting both neutrally.

Write the tool descriptions for two audiences

Your tool descriptions are read by the model at runtime. They are also, in practice, the only per-tool documentation a human ever sees, because most clients surface them directly.

That means one piece of text is doing two jobs, and it can. A good description says what the tool does, when to use it rather than a similar one, and whether it changes anything. The first two help the model choose. The third helps the human decide whether to allow it.

What does not work is writing them as documentation prose and hoping the model copes, or writing them as terse machine hints and expecting a human to understand the risk.

The version question nobody answers

If your server is published as a package, integrators are pinning a version or running the latest on every invocation. Both need something from you.

Say what happens when tools change. If a tool disappears in a new version, an agent that was using it starts failing in a way that looks like a model problem to the person debugging it. That is a changelog entry, and MCP servers need changelogs for exactly the same reason APIs do.

Say whether tool names are stable. A renamed tool is a breaking change with no compiler to catch it.

The shortcut, if your server is generated

Everything above is a lot of writing, and most of it is derivable if the server comes from your API rather than being hand-built.

When the tools are a projection of your OpenAPI document and your SDK configuration, the tool list, the parameter schemas, the deprecations and the side-effect classification are all already known. The page can be generated with the same guarantee as your reference documentation: it cannot describe a tool that does not exist, and it cannot miss one that does.

What still has to be written by a person is the risk framing, which is the part at the top of this post, and that is a page rather than a project.

If you are building this from a spec, generating an MCP server from an OpenAPI spec covers what comes out and what to configure, and how many tools to expose covers the curation that should happen before you document anything. Both are easier when the docs and the server come out of the same document, which is what Octri does with it.