Generate an MCPDoc

Run it

# a hosted server
npx mcpdoc https://mcp.example.com/mcp --by "Your Name"

# ...and its repository, for licence and upkeep
npx mcpdoc https://mcp.example.com/mcp --repo owner/name --by "Your Name"

It writes mcpdoc.json, which is the document, and mcpdoc.html, which renders it. Nothing appears on the page that is not in the JSON, with the same mark and the same source.

Always pass --by

The document records who produced it. Since a publisher's own MCPDoc and an independent one are otherwise identical, the name is what lets a reader tell them apart.

Leave it out and the generator does not stop you. It writes an unnamed reader instead, which is honest and useless in equal measure: a document nobody has put their name to says nothing about whether to believe it.

What it reads

Five calls at the very most, and usually two. One to ask for the tool list, one to the repository host if you named a repository, and between one and three to open the session, because it offers the newest protocol version first and tries the next one down if that is refused. A server that accepts the newest version costs one.

For a server that needs no credential, none of those calls carries one.

What it never does

It does not call any of the server's tools, install anything, run any of the server's code, or write outside the directory you run it in. Asking a server what tools it has is the protocol's own discovery call and it changes nothing on the far side.

Ask for the newest version

The protocol version a server reports is the one you asked for. Ask for an old version and a server that speaks a much newer one will politely agree, and you will write down an answer that is true of your request rather than of the server.

This is not hypothetical. An earlier version of this site published a server as speaking 2024-11-05 purely because the request said so. The same server agreed to 2025-06-18 when asked properly.

The generator asks for the newest version it knows, works downwards if refused, and records what came back, which is the highest the server would agree to.

Servers it cannot reach

A hosted server has an address, so this works today. A server that runs on your own machine over stdio has no address to call, and reading its tool list means running somebody else's code, which is a different proposition from asking a question.

Those are out of reach for now. An MCPDoc for one of them says so rather than guessing, and its tool list stays empty until a person fills it in and puts their name against it.

Writing one by hand

Nothing requires the generator. An MCPDoc is a JSON document and its shape is small enough to write. A publisher who wants to ship one alongside their server can do so, and every fact they write is marked said, which is exactly what it is.