Keep an agent informed while an MCP tool runs for minutes
Send progress against the client's token, stop when the client cancels, and choose between one long call, a job id with a poll hint, and the tasks extension.
How-to › Section 8
Expose your API to agents#
MCP servers, tool schemas, hosting and server-side policy, agent skills and instruction files, and making a site and its docs usable by autonomous callers.
11 guides in 5 topics. Every guide compares its approaches and shows the output its commands printed.
- Build an MCP server 3
- Design tool schemas agents can use 1
- Host, transport and secure an MCP server 3
- Write agent skills and instruction files 1
- Make a docs site agent-ready 3
Build an MCP server 3 guides
Building an MCP server for an API, generated or by hand: openapi-mcp and openapi-mcp-generator, Speakeasy Gram, Stainless MCP, Mintlify, Zapier MCP, Composio, Cloudflare MCP, the go-mcp target generated from a semantic model (SDK Catalog servers, aontu-mcp and the tabnas mcp server as worked examples), and the official MCP SDKs (TypeScript, Python, Go, Java, C#, Rust, Kotlin, Swift) plus FastMCP; tools, resources, prompts, elicitation, wrapping an existing SDK as tools, pruning a generated server to a small tool set, regenerating when the spec changes without losing custom tools.
Run an MCP server against a mock API while you build tools
Point your MCP tools at a mock you can script, so a rate limit or a 500 is one line of fixture rather than a bad afternoon on the real service.
Upgrade an MCP server to a newer protocol revision
Move a server from a handshake-era revision to 2026-07-28 by upgrading the SDK, then prove every client you support still connects with one scripted matrix run.
Design tool schemas agents can use 1 guide
Tools an agent can reason about: naming, descriptions, argument schemas, enums over free text, result shapes, errors as data that tell the agent what to do next, pagination inside a tool result without overflowing context, tool granularity (one tool per entity operation versus one search tool), annotations (readOnlyHint, destructiveHint, idempotentHint), versioning a tool set, and MCP schemas versus OpenAI function schemas versus Claude tool definitions versus Gemini function declarations.
Name tools so an agent picks the right one from fifty
Give every tool a noun and a verb, a description long enough to choose on, and a warning on anything destructive, then measure how often two tools still look alike.
Host, transport and secure an MCP server 3 guides
The server side of running MCP in production: stdio versus Streamable HTTP versus legacy SSE, stateless design, OAuth 2.1 with protected resource metadata, per-agent keys and scopes per tool, rate limits shaped for bursty autonomous traffic, audit trails, deny lists, sanitizing tool results against injection, hosting on Cloudflare Workers, Vercel and containers, server cards at /.well-known/mcp/server-card.json, server.json registry entries, and testing with MCP Inspector and scripted clients.
Choose between stdio and Streamable HTTP for an MCP server
Ship stdio when the agent runs beside your binary and Streamable HTTP when it does not, keep the tools in one module, and keep stdout clean.
Issue and rotate per-agent API keys for an MCP server
Give every agent installation its own key carrying the tools it may call, so a revocation stops one agent rather than every agent.
List an MCP server in the official MCP registry
Publish a server.json to the official MCP registry, prove your namespace from CI with GitHub OIDC, and keep the listing level with each release.
Write agent skills and instruction files 1 guide
Documents an agent reads before it writes code, at repo and package level: AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, SKILL.md against the Anthropic Agent Skills spec with progressive disclosure and bundled scripts, generated skills from a semantic model (the sdkgen Agent Skills surface and aontu agentsmd as options, the tabnas skills repo as an example), what to include and keep out, stopping an agent editing generated files, testing whether Claude Code or Cursor actually uses a skill, keeping several formats in sync from one source, versioning with the code.
Organize agent skills across many related repositories
Keep one shared set of skills for the ecosystem, let each repository override what it needs, and report every shadowed name rather than letting one win in silence.
Make a docs site agent-ready 3 guides
A documentation or product site that agents can use: llms.txt and llms-full.txt, markdown twins and Accept: text/markdown negotiation, AGENTS.md at the site root, a published OpenAPI document at a stable URL, /.well-known/api-catalog (RFC 9727), MCP server cards, an agent-skills index, robots.txt rules per AI crawler, JSON-LD types, RFC 9457 errors on every route, a health endpoint, a docs-search MCP server, and validation tooling (Google Rich Results, the MCP registry CLI, schema linters); per-framework implementation pages for Astro, Docusaurus, Mintlify and Next.js.
Add a health endpoint agents can poll
Return a status, a release id, and one line per dependency, cache it for seconds, and prove the endpoint goes red when a dependency goes down.
Publish an OpenAPI document at a stable URL for agents
Serve the OpenAPI document as JSON and YAML at URLs that do not move, with the headers a browser needs, and a check that fails when the copies drift.
Set robots.txt rules for each AI crawler
Separate the crawlers that train models from the fetchers acting for a person right now, and check each rule against the matching algorithm before you ship it.
Generate the client instead of writing it#
Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.