API guides
Answers to the questions teams ask when they build on an OpenAPI spec: MCP servers for AI agents, SDKs for every language, and documentation people and AI tools can read.
MCP guides
Guides to MCP servers: what MCP is, how it compares to an API, and how to secure, design and test a server in production.
All MCP guidesWhat is MCP? The Model Context Protocol explained
Understand MCP’s hosts, clients, tools and transport through a small server example and the original reason Anthropic introduced it.
Start here8 min readMCP vs API: what is the difference and when to use each
Compare direct REST APIs and MCP tools, including a local 404 experiment and the tradeoffs of tool discovery, context and permissions.
6 min readMCP vs function calling: how they differ and how they work together
Understand how model function calling and MCP work together, using a real developer’s experience building tools for Copilot.
5 min readMCP vs SDK: what each is for, and why you may want both
See how SDKs and MCP servers serve different callers, with a local error-translation exercise and guidelines for using both.
5 min readMCP server examples: 22 real servers, measured and compared
Compare reference, documentation, company and generated MCP servers, including Notion’s firsthand lessons on agent-friendly tools.
8 min readWhat is WebMCP? Tools a web page gives AI agents in the browser
A practical explanation of WebMCP, the browser tool API for agents, with Chrome developer examples, a comparison to backend MCP and security considerations.
7 min readHow to build an MCP server: a step-by-step guide in Python and TypeScript
Build a small MCP server with Python and TypeScript concepts, test its tool contract and understand what changes when you host it remotely.
8 min readHow to generate an MCP server from OpenAPI: mapping, a working generator and pitfalls
Translate OpenAPI operations into MCP tools, see a tested local schema-mapping exercise and learn why curation matters.
7 min readHow to connect an MCP server to Claude: Code, Desktop, claude.ai and the API
Connect an MCP server to Claude Code, Desktop, claude.ai or the API, and learn from a real client-mode configuration bug.
5 min readMCP server configuration: config files for Claude, Cursor and VS Code
Configure local and remote MCP servers in Claude, Cursor and VS Code, including an environment-variable pitfall reproduced locally.
5 min readHow to host a remote MCP server: deploy, secure and scale it
Deploy a remote MCP server with HTTPS, authorization, shared state and limits, informed by Cloudflare engineers’ experience.
5 min readHow to test an MCP server: unit tests, transport checks and real models
Test MCP tool behavior, HTTP transport, interface snapshots and model selection, with a reproducible local test and practical examples.
7 min readMCP security best practices: a checklist for MCP servers
Review MCP server security controls and learn from a researcher’s findings about familiar vulnerabilities in MCP backends.
6 min readMCP OAuth: how MCP server authorization works, step by step
Follow MCP OAuth from discovery to scoped access tokens, with Mux’s firsthand experience of adding hosted authorization.
5 min readMCP token passthrough: why it is forbidden, and the confused deputy
Understand why MCP forbids token passthrough, with a local audience-validation check and safe upstream credential patterns.
5 min readMCP tool poisoning and prompt injection: how they work and how to limit them
Understand MCP tool poisoning and prompt injection through firsthand research, tool-contract review and layered defenses.
5 min readMCP audit logs and rate limits: what to record and how to cap tool calls
Design MCP audit trails and per-tool limits with a reproducible local rate-limit exercise, redacted log fields and production safeguards.
7 min read
SDK generation guides
Answers to the questions teams ask about generating SDKs from an OpenAPI spec: languages, customization, versioning and publishing.
All SDK generation guidesWhat is an SDK? Meaning, parts and examples
What an API SDK contains, how it differs from platform toolkits, and why naming, types and errors determine whether the library is useful.
Start here6 min readSDK vs API: the difference, with code examples
Compare direct API calls and SDK calls with the same paginated task, showing where authentication, cursor handling and error logic live.
5 min readWhat is a client library? Meaning, examples and what's inside
Understand what an API client library does, how official and generated packages differ, and which behaviors callers should inspect.
5 min readWhy build an SDK for your API? Benefits and costs
Why official SDKs reduce repeated integration work, what they cost to maintain, and what Xero learned from relying on community libraries.
5 min readWhich languages should your SDK support? How to choose
Choose SDK languages using API traffic, audience needs and real maintenance capacity, with a lesson from GitHub’s 2026 language data.
5 min readHow to build an SDK: a step-by-step guide with code
Design and build a TypeScript API SDK with a shared transport, safe retries, typed errors and pagination, including a repeatable retry test.
6 min readHow to generate an SDK from OpenAPI: a step-by-step guide
Generate useful client libraries from OpenAPI by improving operation names and schemas, then testing and publishing reproducible packages.
5 min readGenerated vs handwritten SDKs: which should you build?
Choose between generated, handwritten and hybrid SDKs using Algolia’s experience maintaining over 100 packages.
5 min readHow to customize a generated SDK: overlays, hooks and wrappers
Customize a generated SDK through OpenAPI fixes, overlays, generator settings, request hooks and wrappers without patching generated files.
5 min readWhat is an idempotency key? How it works, with examples
Learn how idempotency keys protect retried API writes, including Stripe’s engineering rationale, replay rules and server requirements.
5 min readSDK error handling: how to design errors developers can use
Design SDK errors that preserve response status, request IDs, problem details and retry guidance while distinguishing network failures.
5 min readHow to test an SDK: unit, contract and release tests
Test SDK request construction, errors, pagination, contracts, docs examples and built packages, with an HTTPX mocked-transport exercise.
5 min readhttpx vs requests vs aiohttp: which Python HTTP client to use
Compare requests, HTTPX and aiohttp for Python SDK development using async support, timeout behavior and a local call through all three.
5 min readHow to publish an npm package: a step-by-step guide
Publish an npm SDK safely: inspect the tarball, release a version, and use trusted or staged CI publishing, including npm’s 2026 changes.
5 min readHow to publish a Python package to PyPI: a step-by-step guide
Prepare and publish a Python SDK to PyPI with pyproject.toml, a clean wheel test, TestPyPI and trusted CI publication.
5 min readHow to maintain an SDK: releases, runtimes and support
Keep SDKs current through coordinated API releases, runtime tests, dependency updates and support policies, informed by Stripe’s experience.
5 min readHow to keep SDKs and API docs in sync
Prevent SDK and documentation drift by sharing an OpenAPI contract, generating real code samples, and coordinating package releases.
5 min read
API documentation guides
Step-by-step guides to API documentation: how to write it, document authentication, version it, keep it current and make it readable to AI.
All API documentation guidesWhat is API documentation? Parts and examples
What API documentation is, the four parts every API's docs have, what one reference entry contains, how docs differ from an OpenAPI spec, and where they live.
7 min readWhy do I need API documentation?
Why API documentation matters: how developers choose and learn APIs, what your own team gets from it, why AI assistants depend on it, and when a spec and a README are enough.
8 min readHow to write API documentation: a step-by-step guide
The pages every API needs, from the quickstart and authentication to the API reference, errors and changelog, in the order developers read them.
Start here10 min readAPI reference vs guides: what goes in each
An API reference tells developers what they can call. Guides help them turn those calls into working features. Here's how to write both without making readers search twice.
13 min readHow to document API authentication
What an API authentication page needs: where to get a credential, how to send it, scopes, the 401 and 403 responses, test keys and rotation, with examples for API keys, bearer tokens and OAuth 2.0.
8 min readAPI documentation examples worth learning from
Seven API documentation sites worth studying for their requests, quickstarts, sandbox tests, permissions, version policies, and AI-readable pages.
13 min readHow to keep API documentation up to date
Why API documentation falls behind the API, and the habits that keep the reference, guides, examples and changelog in step with every release.
8 min readWhat is docs-as-code?
Docs-as-code means writing documentation the way you write software: plain text in Git, reviewed in pull requests, checked in CI and published on merge. How it works, the tools, an example and how to start.
7 min readHow to version API documentation
How to publish a reference for each API version, choose the default, mark deprecated versions with a sunset date, write migration guides and keep old versions from competing in search.
8 min readSwagger UI vs hosted API docs: which do you need?
What Swagger UI does well, where it stops, what a hosted API docs site adds, and how to tell which your API needs, or whether to use both.
7 min readBuild vs buy API documentation: how to decide
What building API documentation on open-source tools involves, what a hosted platform takes off your hands, how to compare the cost, and when each one is the right call.
9 min readHow to make API documentation AI-readable
How to make API docs that AI assistants and coding agents can read and use: llms.txt, Markdown copies of every page, the OpenAPI spec, crawler rules, WebMCP tools and an MCP server.
8 min read
API monitoring guides
Answers to the questions teams ask about monitoring an API: uptime checks, error rates, latency and finding why a request failed.
All API monitoring guidesWhat is API monitoring? What to measure and how to set it up
Explore API monitoring signals and blind spots through Cloudflare’s documented regional network incident.
Start here6 min readWhat is observability? Logs, metrics and traces, and the questions they answer
Understand observability, high-cardinality context, logs, metrics and traces through Intercom’s firsthand engineering experience.
6 min readAPI monitoring vs observability: what each one does in an incident
How monitoring detects API incidents and observability explains causes, with a documented GitHub investigation and practical diagnostic steps.
6 min readLogs vs metrics vs traces: what each records, costs and answers
Understand logs, metrics and traces through a local telemetry comparison, including storage tradeoffs and how to correlate signals.
6 min readWhich API metrics should you track? The four golden signals, per operation
Choose API traffic, error, latency and saturation metrics through GitHub’s documented database connection incident.
5 min readWhat is API latency? Phases, p95 and p99, and latency vs response time
Learn API latency phases, p50, p95, p99, tail risk and the difference between server time and the caller experience.
6 min readSLA vs SLO vs SLI: definitions, 99.9% uptime math and error budgets
Compare SLA, SLO and SLI, calculate error budgets, and see how a real Google SRE policy connects reliability targets to releases.
6 min readHow to set up an API health check: liveness, readiness and uptime checks
Set up API liveness, readiness, and external uptime checks, with a local test showing why a simple HTTP 200 can be misleading.
6 min readHow to set up API alerts: thresholds, windows and who gets paged
Design actionable API alerts with thresholds, windows, SLO burn rates, and a reproducible comparison of alert-rule noise.
6 min readWhat is an API status page? What it shows, and what its bars hide
Learn what API status pages should show, what daily uptime bars hide, and how Atlassian communicates incidents.
5 min readHow to find why an API request failed: from a request ID to the root cause
Debug a failed API request with its request ID, status, and trace, illustrated with a tested three-service log dataset.
6 min read
Try it on your own spec
Turn one OpenAPI spec into hosted docs, SDKs in ten languages, an MCP server and monitoring, starting on the Free plan.