mcpdoc // the shape of the document

What an MCPDoc holds

An MCPDoc is a JSON document with six parts: the format version, which server it is about, who produced it, the marked facts, the tool list, and a list of what the publisher did not state. Anything rendered from it shows the mark and the source alongside every value.

The six parts

key	holds
mcpdoc	The format version this document was written against.
subject	The server this is about: its `endpoint`, and its `repository` where one is known.
produced	Who assembled it (`by`) and when (`at`). Every document carries both.
facts	The marked statements about the server. One entry per field.
tools	The tool list, where somebody has read one.
open	What this document does not answer, written out rather than implied.

A fact

Every entry under facts has three fields that are always there, value, mark and from, and a fourth, note, where the value needs explaining. The mark is not decoration, it is the reason a reader can use the value.

"speaks": {
  "value": "2025-06-18",
  "mark":  "seen",
  "from":  "read from the server on 2026-09-20",
  "note":  "the highest version it would agree to; a version is
            whatever the client asked for"
}

said The publisher stated it. from names where, such as their repository description.

seen Read off the wire. from carries the date it was read. A value inferred from prose is never seen, whoever or whatever inferred it.

not published The publisher did not state it. The field still appears, with no value.

The fields a generator can fill without being told

An MCP handshake gives up most of these for free, which is why the format asks for them.

field	what it says	usual mark
answers	Whether the endpoint responded at all.	seen
speaks	The highest protocol version it agreed to.	seen
implements	Which parts of the protocol it declares, such as tools or logging.	seen
identifiesAs	The name the server gives for itself, which need not match its project.	seen
serverVersion	The version the server reports.	seen
toolCount	How many tools it offered.	seen
does	What the server is for, in the publisher's words.	said
licence	The licence on its repository.	seen
archived	Whether its repository is marked no longer maintained.	seen
lastPushed	When its repository last changed.	seen
stars	A measure of attention, not of whether it works.	seen

The tool list

Each tool records its name, the description the server gave, the arguments it takes and which of those are required. The list belongs to the read that produced it and carries that read's date.

{ "name": "navigate",
  "description": "Navigate to a URL",
  "takes": ["url", "sessionId"],
  "required": ["url"] }

Where nobody has read a tool list, tools is empty and the document says so on its face. An MCPDoc that has confirmed nothing is a working document, not a failed one.

What is not answered

open is a plain list of the questions this document does not settle. Writing them down is the point: a reader who cannot see the gaps will assume there are none.

"open": [
  "whether its tools do what they say",
  "what credential it needs to be useful",
  "how to ask it things, in a person's own words"
]

Two silences are worth keeping apart. That a publisher did not state a licence is their gap, and belongs on the document. That nobody has yet connected to the server is the reader's gap, and putting a screen of it on somebody's page charges them for our idleness.

Who produced it

Anybody can generate one of these. A publisher's own MCPDoc and an independent one look identical on the page, and the only thing separating them is the name on the document, which is why produced.by carries the weight it does.

A document with no name against it says nothing about whether to believe it. The generator will write an unnamed reader for anybody who does not pass a name, and a reader should treat that as no name at all.