Dora NodaIn March 2026, the Model Context Protocol's Python and TypeScript SDKs were downloaded 97 million times in a single month, and more than 10,000 public MCP servers were answering tool calls from agents — up from roughly 100,000 SDK downloads at launch in late 2024. By then every major AI client spoke the protocol: Claude, ChatGPT, Cursor, Gemini, Microsoft Copilot, and VS Code. Anthropic had donated MCP to the Linux Foundation's Agentic AI Foundation in December 2025, co-founded with OpenAI and Block, which ended any lingering debate about whether this was one vendor's bet or shared infrastructure.
The numbers kept climbing after March — an independent census counted over 17,000 active servers in Q1 2026 — but the crossing-the-chasm moment is not really about the numbers. It is about what the numbers make true: the primary reader of your infrastructure API is no longer a human with a docs tab open. It is an agent holding a tool list.
That inversion is worth sitting with, because most platform APIs in production today were designed for the old reader. A human opens your docs page, skims the prose, guesses at parameter shapes from a curl example, and pastes an API key into a terminal. An agent never opens your docs page at all.
It connects to your MCP endpoint — one command in Claude Code (claude mcp add --transport http <name> <url>), one entry in Cursor's mcp.json — calls list_tools, and decides what your platform can do from the schemas it gets back. Your prose documentation is now the fallback for the shrinking share of traffic that arrives with eyeballs. Your tool schemas are the interface.
If they are vague, untyped, or missing, the agent does not file a docs complaint. It routes around you to a tool that speaks clearly.
So here is the concrete checklist for making a Render-compatible infrastructure API — or any platform API designed before agents were operators — agent-legible. Six items, in dependency order, each with the specific mistake it fixes.
1. Ship typed tool definitions with honest annotations
The tool schema is the only part of your API the agent is guaranteed to read, so it has to carry the whole contract: flat JSON input schemas, every property typed and described, and descriptions that answer "when to use this tool" rather than restating its name. A deploy_service tool whose environment parameter is an unconstrained string with no description is a coin flip the agent resolves by guessing; one with an enum, a default, and a sentence about which value means production is a decision the agent gets right.
This is also where the MCP spec's tool annotations earn their keep: every tool accepts readOnlyHint, destructiveHint, idempotentHint, and openWorldHint flags that tell the client what the tool may do before it is ever called. Annotate honestly — mark the deploy tool destructive, the status tool read-only — because clients use these hints to decide when to ask the human for confirmation, and a write tool masquerading as read-only is how an agent takes down staging at 2 a.m. without ever triggering a prompt.
The failure mode here is the schema that is technically valid and operationally useless: {"type": "object", "properties": {"input": {"type": "string"}}} passes validation and teaches the agent nothing. If your tool takes a blob of JSON-as-string that only your docs explain, you have not built an MCP tool — you have built a docs page with extra steps, and the agent will hallucinate the blob's shape on every call.
2. Make every write action idempotent, with the key as a tool argument
Agents retry. They retry on timeouts, on dropped SSE streams, on ambiguous errors, and sometimes for no reason your logs can explain. A create_service tool that mints a second service on retry turns every transient failure into a duplicate-billing incident, and the agent has no built-in way to prevent it: MCP defines no protocol-level idempotency key, so the key must travel as an explicit tool argument your server enforces.
Accept something like idempotency_key on every mutating tool, store the key with the result, and return the original result — not an error — when a key repeats. That "return the original, not an error" clause is the part teams skip: a 409 Conflict on a retried key still reads as failure to an agent mid-workflow, while the original success response lets it continue as if the retry never happened.
The same rule covers events and webhooks flowing the other direction: preserve event IDs across retries and make the consuming write tools idempotent, so a redelivered "deploy finished" notification does not trigger a second rollout. If you take one sentence from this post back to your codebase, take this one: any write tool an agent can call will eventually be called twice, and the second call must be free.
3. Return machine-readable errors with codes an agent can branch on
When a human hits 400 Bad Request with a prose message, they read the sentence, infer the fix, and retry. An agent needs the same information in a shape it can branch on: a stable error code, the offending field, and — when the fix is mechanical — the value or action that resolves it. {"code": "SERVICE_NAME_TAKEN", "field": "name", "retryable": false, "suggestion": "name 'api' is taken in environment 'prod'; try a different name"} lets an agent pick a new name and continue; "error": "could not create service" sends it back to guessing, usually by retrying the identical call that just failed. Mark retryability explicitly, because the agent cannot distinguish "try again in a minute" from "this will never work" unless you tell it.
Keep the human-readable message too — errors surface in chat transcripts where the human is watching — but never let prose be the only channel. And resist stuffing remediation instructions into free text when a code would do: codes are stable across releases, prose gets reworded, and every rewording silently breaks the agents that learned to pattern-match your sentences.
4. Serve stateless Streamable HTTP on the current spec revision
The transport story moved fast this year, and servers built against early MCP are now behind a breaking revision. The July 28, 2026 specification revision made the protocol core stateless: the initialize/initialized handshake is gone, protocol-level sessions and the Mcp-Session-Id header are removed, and Streamable HTTP is the remote transport, with Mcp-Method and Mcp-Name headers so gateways can route without inspecting bodies. There is no in-protocol compatibility bridge — clients and servers negotiate the revision explicitly, and a server still demanding session handshakes will simply fail against current clients.
For a platform API this is mostly good news: stateless request/response over plain HTTP is easier to load-balance, easier to cache at the edge, and easier to run behind the gateway you already operate than anything sessionful. But "mostly" carries a migration checklist of its own: verify your server advertises the current revision, drop any session affinity your MCP endpoint relied on, and confirm your gateway forwards the routing headers rather than stripping them. If your MCP server was built before summer 2026 and nobody has touched it since, assume it speaks a dialect current clients have to work around — and schedule the upgrade before the workaround becomes the reason agents prefer a competitor's endpoint.
5. Use auth the agent can actually complete
The spec is blunt on this point: servers must implement existing authentication and authorization rather than inventing parallel identity schemes, enforce least privilege, and log every tool call for audit. In practice that means standard OAuth 2.1/OIDC flows the clients already know how to complete — the browser sign-in behind Claude Code's /mcp command, the OAuth completion Cursor documents for remote entries — not a bespoke "paste this token into a header the client has never heard of" scheme. Pre-register client callbacks with your issuer, keep scopes narrow enough that consent screens do not terrify the human approving them, and remember that some clients request every scope you advertise plus offline_access: an undisciplined scope list turns your consent screen into a wall of checkboxes that kills adoption before the first tool call.
This is also the item most likely to need a shim rather than a rewrite. If your identity provider predates the MCP authorization profile, a small adapter that speaks MCP auth on the client side and plain OAuth on the IdP side beats waiting for your IdP vendor to learn a new dialect — we walked through exactly that shim, including the iss validation gap, in a recent post. Whatever shape it takes, the acceptance test is one sentence: a new user connects your server from stock Claude Code or Cursor and reaches a working tool call without reading your docs.
6. Be discoverable: registries, instructions, and the workflow, not just the tools
The last item is the one teams ship last and agents punish first. A server nobody finds might as well not exist, so list yours in the registries agents and their humans search — the official MCP Registry plus the community indexes — with descriptions written for someone choosing between five similar servers, not for someone who already chose yours. Then, inside the server, set top-level instructions describing the cross-tool workflow: "list services, then describe the one you will act on, then deploy; never deploy without describing first." Individual tool schemas describe atoms; instructions describe the molecule, and without them the agent invents its own ordering — usually the wrong one.
Discovery also means naming tools so they survive a crowded tool list. Action-oriented, namespaced names (deployments_create, deployments_status) beat clever ones (ship_it, check) because the agent sees your tools alongside dozens from other servers, often truncated. Boring names are a feature: they are the names an agent can guess before it even reads your schemas.
What "routed around" looks like
None of this is hypothetical pressure from a future that might arrive. As of April 2026, 78% of enterprise AI teams reported at least one MCP-backed agent in production, and Stacklok's 2026 survey found nearly half of software companies running MCP in production, with 19% reporting broad production use.
Forrester projects that 30% of enterprise application vendors will ship their own MCP server in 2026. When your customer's agent needs to check a deploy status and your platform has no MCP server — or has one with untyped tools, non-idempotent writes, and prose errors — the agent does not wait for your roadmap. It uses the server that works: the competitor's, the community's, or a brittle shell-out to your CLI that breaks on your next release.
That is the actual cost curve. Every week your API stays agent-illegible, more of your users' workflows get built on someone else's tool surface, and switching costs accumulate in the wrong direction. MCP ubiquity did not just add a new integration target; it made "speaks MCP well" the default filter agents apply before they ever evaluate your platform's real merits.
Monday morning: the order of operations
If the checklist reads as a quarter of work, sequence it by blast radius. First, ship read-only tools with typed schemas and honest readOnlyHint annotations — status, logs, list operations — because they are safe to expose, immediately useful to agents, and they force you to solve transport, auth, and discovery once, on tools that cannot break anything.
Second, add writes behind explicit idempotency keys and machine-readable errors, one workflow at a time, starting with the action your users already ask agents to perform through workarounds. Third, register everywhere, write the server instructions, and rename anything clever. Then watch your tool-call logs the way you used to watch your docs analytics: the calls tell you what agents actually do with your platform, which is now the same question as what your users do with it.
Bex.co is the open-source, AI-native Render alternative — push a git repo, get a running HTTPS service on machines you own, with a Render-compatible API designed for agents as first-class operators. Star the repo on GitHub or deploy your first app today.
