Your coding agent can scaffold a REST endpoint, write tests, and open a PR — all without you touching the keyboard. But can it write good API documentation? We ran the same task through three leading coding agents — Claude Code, Cursor, and Codex (OpenAI) — and asked each one to document a small API from source code alone. Here's what we found, and what it tells you about where AI-assisted documentation is heading.
The task
A Node.js Express API with six endpoints: auth, users (CRUD), and a webhook receiver. No OpenAPI file. No existing docs. Just source code and a one-line prompt:
"Read this codebase and document the API."
We measured: completeness (were all endpoints captured?), accuracy (did params, types, and response shapes match the code?), structure (was the output usable without heavy editing?), and MCP-readiness (could the output power an AI agent tool call?).
Claude Code
Completeness: ★★★★★ All six endpoints, all params, correct auth headers.
Accuracy: High. Claude Code reads the actual route handlers and infers types from usage — it caught an optional ?include_deleted=true query param that wasn't in any README.
Structure: Good. Output was Markdown with clear H2 headings per endpoint, request/response examples, and a note about the webhook HMAC signature requirement.
MCP-readiness: With DocStar wired in, Claude Code's output maps directly to hosted MCP tool definitions — no reformatting required. The search_, get_, and call_ tools are populated from the same structured data the agent just wrote.
Verdict: Best overall. Strongest at reading implicit context (middleware, shared validators) that other agents miss.
Cursor
Completeness: ★★★★☆ Caught five of six endpoints; missed the webhook receiver because it was in a separate routes/webhooks.js file not imported from the main router.
Accuracy: Solid on the endpoints it did catch. Cursor's strength is inline editing — it's fast and the output slots neatly into an existing docs file.
Structure: Very good if you already have a docs template. Cursor respects your existing format and fills it in. Without a template, the output is flat Markdown.
MCP-readiness: Requires an intermediate step. Cursor's output needs to be imported into a documentation platform before it can power MCP tools. There's no native path from Cursor → hosted MCP server.
Verdict: Best for teams that already have a docs framework and want an agent to fill gaps. Weaker for greenfield documentation.
Codex (OpenAI)
Completeness: ★★★☆☆ Four of six endpoints. Missed the webhook receiver and merged two user endpoints into one.
Accuracy: Mixed. Codex hallucinated a PUT /users/:id/role endpoint that doesn't exist, and got the response shape of the auth endpoint wrong (listed access_token instead of token).
Structure: The output read more like a comment block than a developer reference. Needed substantial editing before it was publishable.
MCP-readiness: Not applicable without further tooling.
Verdict: Codex is a strong code-generation tool but not yet a reliable documentation writer. Use it for logic, not for consumer-facing API reference.
What makes API docs agent-ready?
The results reveal three things that separate good agent-written docs from bad ones:
-
Source reading depth. Agents that only scan
index.jsmiss routes defined in sub-files. Claude Code follows imports; Cursor partially does; Codex largely doesn't. -
Type inference. Without a TypeScript schema or explicit JSDoc, agents have to infer types from how variables are used. Claude Code does this well. The others default to
stringfor almost everything. - Output structure. Docs that go straight to a hosting platform (and then to an MCP server) need consistent structure — endpoint name, method, path, params with types, request body, response examples, auth. Freeform Markdown doesn't cut it.
The missing layer: getting from agent output to a live MCP server
Even with Claude Code's strong output, there's a gap between "agent wrote the docs" and "those docs power an MCP server your users can connect to." That gap is a platform. DocStar closes it. Paste one prompt in Claude Code, Cursor, or Codex — DocStar reads the output (or reads the source directly), structures it, and publishes:
- A hosted API docs site with a try-it playground
- An
llms.txtand markdown twin for LLM consumption - A hosted MCP server with three ready-made tools per API:
search_,get_, andcall_ - A branded CLI and an OpenAPI 3 file
All kept in sync with your repo. No separate documentation editor. No OpenAPI file required upfront. MSG91 (docs.msg91.com) runs on DocStar today.
What to do right now
- Pick your coding agent (Claude Code is the strongest for docs today).
- Run: "Read this codebase and document the API."
- Pipe the output into DocStar — free plan, no credit card.
- Get a live docs site,
llms.txt, and hosted MCP server in minutes.
Your API should be readable by humans and AI agents. Most APIs today are neither. Fix both in one step.
DocStar publishes AI-first API docs, hosted MCP servers, and developer CLIs from one coding-agent prompt. Free to start.
Top comments (1)
The webhook miss is the telling bit for me, a separate routes file not imported from the main router is easy for an agent to walk past.