DEV Community: Swayam Maheshwari

Claude Code vs Cursor vs Codex: Which Coding Agent Writes the Best API Docs?

Swayam Maheshwari — Thu, 29 Oct 2026 11:29:42 +0000

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.js miss 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 string for 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.txt and markdown twin for LLM consumption
A hosted MCP server with three ready-made tools per API: search_, get_, and call_
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.io

DocStar publishes AI-first API docs, hosted MCP servers, and developer CLIs from one coding-agent prompt. Free to start.

Why Your API Is Invisible to AI Assistants (And How to Fix It)

Swayam Maheshwari — Wed, 28 Oct 2026 12:03:32 +0000

Why Your API Is Invisible to AI Assistants (And How to Fix It)

Developers are integrating APIs differently now. They open Claude, Cursor, or ChatGPT, describe what they need, and expect the AI to find the right endpoint, read the contract, and generate working code. If your API is not explicitly structured for AI consumption, the assistant skips it and recommends a competitor that is. This is the AI discoverability gap. Most APIs have it. Here is what causes it and how to close it.

The AI Discoverability Gap

Search engines index text. AI assistants index structured context — they need to know what an endpoint does, what parameters it accepts, what errors it returns, and how to authenticate. An HTML docs page is not enough. When a developer asks an AI assistant "how do I send an SMS via API?", the assistant pulls from whatever is in its context or can be retrieved via tools. If your API has no llms.txt, no MCP server, and no machine-readable OpenAPI spec linked anywhere the assistant can reach, you are invisible. Mintlify, ReadMe, and Stoplight are all adding MCP endpoints right now. The race for AI discoverability is already underway.

What MCP Actually Is

MCP stands for Model Context Protocol. It is an open protocol (originally from Anthropic, now adopted broadly) that lets AI assistants call external tools in a structured, safe, and authenticated way. Instead of copy-pasting your docs into a chat window, a developer connects their AI coding agent to your MCP server once. From that point on, the agent can:

Search your documentation in plain language
Read the exact endpoint contract (methods, params, responses, auth)
Make real API calls on behalf of the user

Think of it as giving your API a direct line into every AI assistant your users already have open.

The Three MCP Tools Every API Needs

A well-structured MCP server exposes at least three tools:

1. `search_<api>_docs`

Plain-language search across your documentation. The agent types a question; your MCP returns the relevant sections. No hallucination, no guessing.

2. `get_<api>_api_docs`

Returns the exact endpoint contract: HTTP method, URL, path params, query params, request body schema, response schema, error codes, and examples. This is what the agent uses to generate correct code.

3. `call_any_api_of_<api>`

Makes a real, authenticated request to your API on behalf of the user. OAuth-signed. No credentials in the chat window.

These three tools cover discovery, reading, and execution — the full loop an AI agent needs to use your API without human hand-holding.

What `llms.txt` Does — And Why It Matters

llms.txt is a plain-text file at the root of your docs site that tells AI systems what your product is, what endpoints exist, and how to read your documentation. It is to LLMs what robots.txt is to crawlers. A minimal llms.txt looks like this:

# MyAPI
> MyAPI lets you send SMS, email, and WhatsApp messages programmatically.

## Endpoints
- [Send SMS](/docs/sms/send)
- [Send Email](/docs/email/send)
- [Delivery Webhooks](/docs/webhooks)

## Authentication
Bearer token. Get yours at https://app.myapi.com/keys

When an AI assistant is asked about messaging APIs, it can now find this file, understand your product scope immediately, and link to the right docs. Without it, you rely on the assistant having seen your site in its training data — which may be months out of date.

How DocStar Makes This Automatic

Building and maintaining an MCP server, an llms.txt, and an OpenAPI spec by hand is real engineering work. It goes stale every time the codebase changes. DocStar automates the entire stack from a single agent prompt. You paste one instruction into Claude Code, Cursor, or Codex. The agent reads your codebase and DocStar publishes:

A hosted docs site with a try-it playground
An MCP server with the three tools above, on your own domain
llms.txt and markdown twins for AI indexing
An OpenAPI 3 file for tooling compatibility
A branded CLI (your-api mcp for local connections)

Everything stays in sync with GitHub. No documentation editor to learn. No OpenAPI file to write first. MSG91 (docs.msg91.com) uses DocStar in production — their MCP server is live and their docs are AI-readable today.

What to Do Today

Check your discoverability — ask Claude or ChatGPT: "How do I use [your API name]?" If it guesses or refuses, you have a gap.
Add llms.txt — even a minimal file is better than none.
Stand up an MCP server — either build one or use a platform that generates it from your codebase.
Keep it in sync — tie your docs pipeline to your CI/CD so docs update when code updates.

AI assistants are becoming the primary interface developers use to discover and integrate APIs. If your API is not structured for AI consumption, you are not just harder to use — you are invisible.

DEV Community: Swayam Maheshwari

Claude Code vs Cursor vs Codex: Which Coding Agent Writes the Best API Docs?

The task

Claude Code

Cursor

Codex (OpenAI)

What makes API docs agent-ready?

The missing layer: getting from agent output to a live MCP server

What to do right now

Why Your API Is Invisible to AI Assistants (And How to Fix It)

Why Your API Is Invisible to AI Assistants (And How to Fix It)

The AI Discoverability Gap

What MCP Actually Is

The Three MCP Tools Every API Needs

1. search_<api>_docs

2. get_<api>_api_docs

3. call_any_api_of_<api>

What llms.txt Does — And Why It Matters

How DocStar Makes This Automatic

What to Do Today

1. `search_<api>_docs`

2. `get_<api>_api_docs`

3. `call_any_api_of_<api>`

What `llms.txt` Does — And Why It Matters