MCP vs API: why your API docs doesn't cover your MCP server

A team ships an MCP server on a Thursday. The API behind it is stable, the reference docs are current, and the server exposes the same endpoints those docs already describe. As far as anyone involved is concerned, it is documented.

Two weeks later adoption is flat. No support tickets, no bug reports, no frustrated developers in the community channel. Nothing at all.

What happened is that an agent connected, read the tool list, could not tell two of the tools apart, called the wrong one and failed. Then it moved on to something that worked. The gap between MCP vs API documentation is not a difference of degree, and an API reference was never going to close it.

This post covers what changes when the client is an agent, the six things an MCP server actually needs documented, and how to test whether yours is working.

What changes when the client is an agent

An API is documented for a developer who reads, decides, and then writes code. An MCP server is consumed by an agent that reads tool definitions and calls them immediately, with no browsing and no second visit. The documentation stops being a page somebody navigates and becomes metadata the caller acts on.

Machine against human is the obvious framing, and it is the less useful one. What actually separates them is when the reader can still recover. A developer who misreads a reference page senses something is off, backs up, reads the next section. An agent that misreads a tool description has already made the call.

The bottom row is why this stays invisible. A developer who cannot finish an integration eventually complains to someone. An agent that picks the wrong tool produces a bad result, the person supervising it blames the product, and no signal ever reaches the team that owns the docs.

Why API reference documentation does not transfer

API reference answers one question well: what does this endpoint do. An MCP tool definition has to answer a different one: when should I choose this over the alternatives, and what happens if I do. Reference documentation assumes a reader who can weigh options across several pages, and that is the one thing an agent working from a tool list cannot do.

Three failures follow from that, and they show up most often in mcp documentation written by teams who already had good API docs.

The description field is doing all the work. A tool description is not a label, it is the entire basis on which the tool gets picked or skipped, and most teams write it the way they would name a variable. Four words gives the agent nothing to choose on.

There is also nowhere to hide detail. A developer portal can put a concept on one page and its important caveat three clicks deeper, which works because a human follows links. An agent sees the tool list and the schema, so anything that matters has to sit at the point of the call or it may as well not exist.

And ambiguity between two tools stops being annoying and starts being fatal. Two similar names with similar descriptions is a coin flip on every call. In a reference doc, two adjacent endpoints with overlapping names cost a developer thirty seconds of reading.

The version of this we see most often is a server exposing both a single-item and a batch version of the same operation, described identically apart from the word "multiple." An agent handed one item will sometimes reach for the batch tool and pass an array of one, which works, and sometimes reach for it and pass a bare object, which does not. The API is fine. The two sentences describing it are not.

What an MCP server actually needs documented

Six things, and only one of them appears in a typical API reference. Working through them in order is the fastest way to take an undocumented server to a usable one.

1. Tool names and descriptions written to be chosen between

Write each description to answer what the tool does, when to use it, and when not to. The third part is the one everybody skips and the one that prevents wrong calls.

Compare these two descriptions for the same tool:

Weak. create_payment: Creates a payment.

Better. create_payment: Creates and immediately submits a single payment to a saved recipient. Use when the recipient already exists and the amount is known. Do not use for recurring payments, use create_subscription, or for payments to a new recipient, which require create_recipient first.

The second version does not describe the endpoint any more accurately. It describes the decision, which is the thing the caller is actually stuck on.

2. Parameter descriptions with real constraints

A JSON schema says a field is a string. It does not say which strings are valid, and an agent will invent a plausible one. Enumerate the accepted values and state the format. Say what happens at the boundaries.

The same applies on the way back out. Tools can declare an output schema, and describing what comes back saves the agent guessing at the shape of your response before it can use it.

3. Errors that state the recovery path

A developer reads a 422 and works out what to change. An agent needs the error itself to say what to do differently, because it has no other source of that information. An error that says "invalid currency" is a dead end. An error that says "invalid currency, accepted values are the ISO 4217 codes listed in the currency parameter" is recoverable in one step.

4. Permission and scope, stated

What is this server allowed to do on the user's behalf, written down rather than implied by whichever tools happen to be exposed. It is the first question a security review asks, and an unanswered version of it stalls deals for weeks.

Be specific about the boundary. Which tools move money or change state, which only read, whether the credential is scoped per user or shared across a workspace, and what an operator can revoke. Teams tend to document the happy path and leave the limits to be discovered, which is exactly backwards for a caller that cannot ask.

5. Side effects, marked

Whether a call is read-only, destructive, or safe to repeat. MCP has annotations for exactly this: readOnlyHint, destructiveHint, idempotentHint and openWorldHint.

The defaults are the part worth knowing. destructiveHint and openWorldHint both default to true, so a tool carrying no annotations is assumed to be destructive and assumed to reach outside your system. An unannotated tool reads as dangerous, and a careful client will handle a read the same way it handles a write.

They are hints rather than guarantees. The spec requires clients to treat annotations from an untrusted server as untrusted, which makes them documentation for a caller who already trusts you, not a security control.

One caveat covering all six. MCP is young enough that the specifics move. The remote transport has already been rewritten once, with the old HTTP and SSE pairing replaced by Streamable HTTP, and some of what is written above will read as dated by the time your server reaches its third release. The six categories have held up so far. The field names may not, so check the spec rather than this page.

6. Rate limits and cost

An agent will retry in a loop unless something tells it not to. If a call is metered or throttled, that belongs in the tool definition, not in a pricing page the agent will never see.

Tools are not the only surface

Most MCP servers lead with tools, and most of this article is about tools, because that is where the calls happen. The protocol also supports resources, which are data the client can read, and prompts, which are templates a user invokes deliberately. Both need documenting and both get skipped.

The distinction worth holding onto is who initiates. A tool is chosen by the model, a resource is pulled in by the application, and a prompt is picked by a person. That changes what the description has to do in each case. A tool description is a decision aid. A resource description is a label on something already being read. A prompt description is read by a human choosing from a menu.

If your server exposes resources, document what each one contains and how fresh it is, because an agent reasoning over stale data fails in a way that looks like a reasoning error rather than a data error. That misattribution is expensive, since the team debugging it starts in the wrong place.

The human layer you still need

Somebody has to install the server, authenticate it, and connect it to a client, and that somebody is a developer reading a page. MCP does not remove the need for human-facing documentation. It adds a second surface next to it.

For mcp integration to work in practice, that page has to cover which transport you support, stdio or Streamable HTTP, how credentials are obtained and stored, which clients you have actually tested against, and how a developer confirms the connection is live before trying real work. A getting started page for your API does not answer any of those.

This is also where most teams underestimate the work. Two surfaces, one for the agent and one for the person configuring it, both of which go stale on the same release.

How to test whether your MCP server is documented

Point a fresh agent at your server with a real task and no hints, then see whether it finishes. That is the MCP equivalent of measuring time to first successful API call, and it is the only test that reflects what happens in production.

The check takes an afternoon:

• Pick three tasks a real customer would want done through your product.

• Give an agent access to the server and the task, and nothing else. No guidance about which tool to use.

• Record whether it chose the right tool on the first attempt, and where it went wrong when it did not.

• Fix the description, not the prompt.

That last one is the whole point. It is tempting to rescue a failed run by explaining more in the prompt, and it proves nothing, because your customers will not be writing your prompts.

What this looks like across real fintech portals

Across the 165 fintech developer portals we audited ahead of Money20/20, the most common AI-readiness failure was not a missing MCP server. It was that the documentation itself could not be read cleanly by a machine, which means the groundwork an MCP would sit on was not there either.

We have not audited MCP servers at that scale, and putting a percentage on MCP adoption would be inventing one. What we can report is the pattern.

Six failure types showed up repeatedly across those portals. One of them was that adding .md to a documentation URL returned the rendered website instead of clean text. An AI coding tool pointed at those pages scrapes a layout rather than reading content, and produces broken integration code with total confidence.

Revolut is a useful reference point because it sits at the strong end of the category. Guides, API reference and SDKs are kept in separate sections, pages ship a markdown version, and there is a copy-to-Claude option on the page. It still has no MCP.

The category is mostly sitting in that gap. The companies that did the work to make their documentation machine readable have mostly not taken the next step, and the ones that have shipped an MCP server have mostly shipped it undocumented.

Common pitfalls

Four of these come up more than the rest.

Exposing every endpoint as a tool. A hundred tools is not coverage, it is an unreadable list, and it makes every selection harder. Expose the workflows customers actually ask for rather than your API surface.

If we could only fix one of these, it would be that one. Everything else on this list gets easier to diagnose once the tool list is short enough to read.

Copying reference prose straight into description fields. That prose was written for a reader who has the surrounding page in front of them. Pasted into a description it loses the thing that made it work.

Leaving the annotations unset. The defaults assume the worst, so every read-only tool you ship gets handled as though it might delete something.

Documenting the server once. Tool descriptions go stale on the same release cadence as everything else, and they fail more quietly, because nobody is reading them.

Where MCP documentation belongs in your docs architecture

An MCP server is a fourth surface alongside guides, API reference and SDKs. It is not a separate site and it is not a page bolted onto the reference, and it needs an owner for the same reason the other three do.

The failure mode is predictable. An engineer ships the server as a project, writes the tool descriptions in an afternoon, and nobody touches them again. Three releases later the API has moved and the descriptions describe a product that no longer exists. There is no ticket queue for that, and no dashboard where it shows up.

Also read: structuring documentation across multiple products

Also read: what bad API documentation actually costs

Key takeaways

• MCP vs API documentation differ on reader and recovery. A developer who misreads a page tries again, an agent that misreads a tool description has already made the call.

• The tool description is the documentation. It has to say what the tool does, when to use it, and when to use something else.

• Six things need documenting: descriptions, parameter constraints, recoverable errors, permission scope, marked side effects, and limits.

• You still need a human-facing page for install, credentials and tested clients. MCP adds a surface, it does not replace one.

• Test it by giving a cold agent a real task and fixing the description rather than the prompt.

Most companies treating MCP as an engineering project will ship a server nobody can use and never find out why. The protocol is the easy part. Keeping tool descriptions true after the API moves is the hard part, and that is the same ownership problem their API documentation already has, on a surface where failure is completely silent.

see what this looks like for real clients