# Agent-native APIs: is "plain HTTP + token + /api/docs" right in 2026?

Compiled 2026-09-07. Every number carries a URL and date. "(est.)" marks the source's own estimate or my inference.

## 1. Competing interfaces, status September 2026

**MCP (Model Context Protocol)**
- Donated to the Linux Foundation's Agentic AI Foundation on 2025-12-09 with OpenAI and Block as co-founders; Google, Microsoft, AWS, Cloudflare, Bloomberg supporting. Anthropic claimed "over 97 million monthly SDK downloads" and "10,000 active servers", first-class support in ChatGPT, Claude, Cursor, Gemini, Copilot, VS Code. https://blog.modelcontextprotocol.io/posts/2025-12-09-mcp-joins-agentic-ai-foundation/
- Third-party tracker: ~9,400 servers across PulseMCP/official registry/Smithery/mcp.so by mid-April 2026, up from ~6,800 at end-2025 (est., dedup caveats). https://www.digitalapplied.com/blog/mcp-ecosystem-h1-2026-retrospective-adoption-data-points
- Context bloat is acknowledged by Anthropic itself: "Code execution with MCP" (2025-11-04) reports a 150,000 -> 2,000 token drop (98.7%) by presenting MCP servers as code APIs instead of loading tool definitions. https://www.anthropic.com/engineering/code-execution-with-mcp
- Anthropic's Tool Search docs: five typical MCP servers consume ~55k tokens before work starts; tool-selection accuracy degrades past 30-50 tools. https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool
- Claude Code (Jan 2026) auto-switches to search-based MCP loading once tool descriptions exceed 10% of context; 7+ servers were costing ~67k tokens. https://tessl.io/blog/anthropic-brings-mcp-tool-search-to-claude-code
- Cloudflare "Code Mode" (2026-02-20): its whole 2,500-endpoint API in ~1,000 tokens vs 1.17M tokens as naive MCP tools (99.9%). https://blog.cloudflare.com/code-mode-mcp/
- Auth: Solo.io (2025-08-14): "Enterprises don't allow anonymous DCR ... they don't use authorization-code flows internally." https://www.solo.io/blog/mcp-authorization-is-a-non-starter-for-enterprise. The 2026-07-28 spec formally deprecated Dynamic Client Registration in favour of Client ID Metadata Documents (WorkOS, 2026-08-12). https://workos.com/blog/mcp-client-identity-dcr-cimd-auth-md
- Agent success on real MCP servers is mediocre: MCPMark (2025-09-28, 127 tasks, 5 servers) best model gpt-5-medium 52.56% pass@1; Sonnet 4 and o3 under 30%. https://huggingface.co/papers/2509.24002

**CLI / "just curl"**
- Peter Steinberger (OpenClaw), 2026-01: "mcp were a mistake. bash is better." https://x.com/steipete/status/2007876353463660757
- Armin Ronacher (2025-08-18): one code-executing "ubertool" beats 30 MCP tools; "the command line ... is a series of tools that can be composed through a programming language: bash." https://lucumr.pocoo.org/2025/8/18/code-mcps/
- Scalekit benchmark (2026-03-11, GitHub, Claude Sonnet 4, 5 read-only tasks x 5 runs): CLI 1,365-9,386 tokens/task vs MCP 32,000-82,835 (4-32x); CLI 25/25 success, MCP 18/25 (72%) - all MCP failures were TCP timeouts to GitHub's hosted server, not model errors. https://www.scalekit.com/blog/mcp-vs-cli-use
- Firecrawl's roundup (updated 2026-06-05) repeats those numbers, quotes Karpathy ("CLIs are super exciting... agents can natively and easily use them") and StackOne's rebuttal: the debate "benchmarks the 5% of integrations where comparison makes sense. The other 95% are SaaS systems where no CLI exists." https://www.firecrawl.dev/blog/mcp-vs-cli
- Arcade (2026-03-13): "These agents already know how to use the CLI. They've been trained on millions of shell sessions. curl, git, docker, npm." https://www.arcade.dev/blog/curl-for-mcp/

**Plain REST + docs**
- ModelsLab (2026-03-02, upd. 2026-07-27): "The best thing MCP did ... is push companies to open up more APIs. The protocol itself is optional." https://modelslab.com/blog/api/mcp-vs-rest-api-ai-agents-2026
- WorkOS "Agent experience" (2026-05-21): "Agents are API-first users, whether you like it or not"; "most LLM-based agents can consume an OpenAPI spec directly." https://workos.com/blog/agent-experience-oujuh
- Vercel Academy course "Agent-Friendly APIs" (no date on page) teaches exactly Gocha's pattern: endpoint signatures in code blocks, parameter tables, "Curl examples with real values", full response bodies, exhaustive errors, then a Skill on top. https://vercel.com/academy/agent-friendly-apis/agent-friendly-docs

**Markdown docs for agents**
- Cloudflare "Markdown for Agents" (2026-02-12): `Accept: text/markdown` conversion at the edge. https://developers.cloudflare.com/changelog/post/2026-02-12-markdown-for-agents/
- Checkly (2026-02-19): only 3 of 7 agents send `Accept: text/markdown` (Claude Code, Cursor, OpenCode; not Codex, Gemini CLI, Copilot, Windsurf); markdown cut one docs page from 615 KB to 2.3 KB. https://www.checklyhq.com/blog/state-of-ai-agent-content-negotation/
- Vercel serves every docs URL as `.md`, plus llms.txt, sitemap.md, graph.json (updated 2026-09-03). https://vercel.com/docs/agent-resources/markdown-access
- One site's 44-day log: 1,421 markdown requests, 35% from "Claude" UA (small sample). https://www.suganthan.com/blog/cloudflare-markdown-for-agents/

**llms.txt**
- 8.7% of top-1,000 sites (87 files) and 5.6% of top-10,000 as of June 2026, up from 0.3% a year earlier. https://www.rankability.com/data/llms-txt-adoption/
- Casey Burridge (2026-06-20, ~7,500 sites): 5.61%; "None of the major AI search providers have publicly confirmed they read these files"; ChatGPT/Claude/Gemini do not host one themselves. https://caseyrb.com/blog/state-of-llms-txt-adoption/
- Google's John Mueller (2025-06-17): "FWIW no AI system currently uses llms.txt." https://www.seroundtable.com/google-ai-llms-txt-39607.html
- Vendor consumption of llms.txt as a first-class signal: not found. (Coding agents do fetch it when a page tells them to.)

**Agent Skills / SKILL.md** - Anthropic-originated open format; agentskills.io lists ~45 supporting clients including Claude Code, ChatGPT/Codex, Cursor, Gemini CLI, Copilot, VS Code, Goose, OpenClaw. https://agentskills.io/home. Speakeasy (2026-02-19): "Skills describe the workflow. MCP provides the runner." https://www.speakeasy.com/blog/skills-vs-mcp/

**A2A** - 150+ organizations, 22k+ GitHub stars, in Azure AI Foundry, Bedrock AgentCore, Google Cloud (2026-04-09). Agent-to-agent, not tool-to-agent; not a competitor to a REST tool API. https://www.linuxfoundation.org/press/a2a-protocol-surpasses-150-organizations-lands-in-major-cloud-platforms-and-sees-enterprise-production-use-in-first-year

**x402 / agentic payments** - 169M transactions, 590k buyers, 100k sellers in year one; AWS CloudFront/WAF GA and Cloudflare Monetization Gateway waitlist (2026-07-06). https://www.infoq.com/news/2026/07/cloudflare-aws-x402-micropayment/. Stripe ships an Agent Toolkit plus an MCP server and agent-initiated payments. https://stripe.com/guides/agentic-commerce

**"Agent-native / agent-first" as a term** - Used by Vercel ("Agent-Friendly APIs", "agent-resources"), Browserbase ("a Search API optimized for agents, accessible via our REST API ... JSON, Markdown or HTML", 2026-03-17) https://www.browserbase.com/blog/search, WorkOS ("agent experience"). Firecrawl's "For Agents" page offers a keyless MCP endpoint first and a bearer key for full access. https://docs.firecrawl.dev/mcp-server/keyless. Exa/Resend explicit "agent-native" positioning: not found in this pass.

## 2. Named opinions and evidence

For "clean HTTP + docs": Steinberger, Ronacher, Karpathy, Arcade, ModelsLab, WorkOS (above). Kaxil Naik (2026-04-07) splits the difference: "MCP the protocol is fine. MCP servers built by auto-converting 80 REST endpoints into 80 MCP tools are what poison the context window." https://kaxil.substack.com/p/mcp-vs-cli-vs-rest

For "ship MCP": Allen Hutchison (2026-03-14): "Not every agent has a shell. And not every agent is an interactive coding assistant" - ChatGPT, Claude.ai, mobile and hosted agents can only reach you via MCP/connectors. https://allen.hutchison.org/2026/03/14/mcp-isnt-dead-you-just-arent-the-target-audience/. Matthew Hall (2026-03-04) defends MCP's schemas as durable value despite "100+ zombie Node processes." https://matthewhall.com/posts/mcp-isnt-dead-were-just-early/

Benchmarks: only Scalekit's small CLI-vs-MCP test (above) and MCP-only benchmarks (MCPMark, MCP-Universe, LiveMCPBench). A controlled REST-vs-MCP-vs-CLI success benchmark: not found.

Failure postmortems: "How APIs fail when agents use them" (2026-03-31, 1,099 APIs) lists silent token expiry, 429s without `Retry-After`, "silent quota enforcement via 200", missing idempotency, missing request IDs; scores Stripe 8.1/10, HubSpot 4.6/10. https://dev.to/supertrained/how-apis-fail-when-agents-use-them-a-failure-engineering-guide-5c1g. Scalekit's 7/25 MCP failures were infra timeouts. Claude Code users demanding pre-configured OAuth clients instead of DCR: https://github.com/anthropics/claude-code/issues/26675

## 3. Design consensus (converging across WorkOS, freeCodeCamp 2026-05-28, Vercel, the failure guide)

- Auth: bearer token in a header; scopes like `orders:read`/`orders:write`; short-lived or revocable keys. OAuth only where a human user must delegate. https://www.freecodecamp.org/news/how-to-design-apis-for-ai-agents/
- Idempotency keys on every write; lookup-by-client-reference for reconciliation.
- Long jobs: `202 Accepted` + job id + poll, webhooks optional; explicit terminal states.
- Errors: stable machine `error_code` + human message + next action; 429 with `Retry-After`; never 200-with-no-effect; request id on every response.
- Docs: markdown at a stable URL (`.md` or `Accept: text/markdown`), real-value curl examples, complete response bodies, exhaustive error table, workflow sequences; OpenAPI as a contract for MCP/SDK generation. llms.txt is cheap but unproven.
- Pricing: per-call/credit pricing dominates; x402 HTTP-402 micropayments are live at AWS/Cloudflare but volume is crypto-native (est.: niche outside that world).

## 4. Verdict

Gocha's approach is correct and, by mid-2026, mainstream among builders of developer-facing tools - it is what Vercel teaches, what Browserbase/Firecrawl ship first, and what the Anthropic and Cloudflare token-economics posts implicitly endorse (agents writing curl/code against an API beats loading tool schemas). It is contrarian only relative to the 2025 "everything must be an MCP server" wave, and the correct hedge is the one he already plans: a thin MCP shim (ideally 2-3 tools or a code-mode style `execute`) generated from the same docs. It is not outdated; the outdated position is 80 auto-generated MCP tools with anonymous OAuth DCR.

Strongest counterarguments:
1. Distribution: ChatGPT, Claude.ai, Gemini and enterprise Copilot users have no shell; without MCP/a connector, those surfaces cannot use the tool at all (Hutchison; Firecrawl/StackOne's "95% of integrations").
2. Governance: enterprises want per-user OAuth, audit, revocation and a registry entry; a static bearer token in an agent's environment is a leaked-secret risk and does not answer "on whose authority" (WorkOS, Solo.io).
3. Evidence gap: no controlled study shows agents succeed more with REST docs than MCP; the pro-CLI numbers are token costs and one 25-run test, and MCPMark shows agents fail ~50% of realistic tasks regardless of transport - docs quality, not protocol, may be the real variable.

Counts: 27 web searches, 30 page fetches, 37 distinct URLs cited, 4 items marked "not found".