Field notes
The MCPOrbit blog.
Product updates, engineering decisions, and field notes from the team building the desktop client for the Model Context Protocol.
All posts
46 posts
Explainer
How do you write good descriptions for MCP tools?
A good MCP tool description starts with a verb, states its inputs and output, and says when not to use it. Here is what to include, with a before-and-after example.
6 min read
Build-it
How to log from an MCP server (logging is deprecated)
The MCP logging capability was deprecated on 2026-07-28. Log to stderr as JSON instead, and learn which stdout writes really corrupt a stdio server.
9 min read
Build-it
How to Build an MCP Server for MongoDB
Build a MongoDB MCP server in Python that lists collections and queries documents, with a filter guard that turns a model's {"$where": "..."} into a tool error instead of server-side JavaScript.
9 min read
Tutorial
How to build an MCP server for a SQLite database
Build a read-only Model Context Protocol server over a SQLite database in TypeScript: list tables, describe schema, and run SELECT queries. Runnable code.
11 min read
Tutorial
How to add an MCP server to Claude Desktop, Cursor, and VS Code
Add an MCP server to Claude Desktop, Cursor, or VS Code by editing one JSON config file: a command for a local server, a URL for a remote one. Then restart.
6 min read
Build-it
How to Build an MCP Server for the Filesystem
Build a filesystem MCP server in Python that reads, writes, and lists files, sandboxed to one directory so a path like ../../etc/passwd is refused.
8 min read
Field notes
How to build an MCP server in TypeScript
Build an MCP server in TypeScript with the official v2 SDK: register tools with Zod schemas and serve over stdio. Full runnable code, tested on SDK 2.0.0.
9 min read
Explainer
How does an MCP server ask the client for input now? Multi Round-Trip Requests
The 2026-07-28 MCP spec is stateless, so a server can no longer hold a stream open to ask the client a question mid-call. Instead a tool returns an InputRequiredResult carrying inputRequests and an opaque requestState, and the client re-issues the same call with inputResponses. That pattern is Multi Round-Trip Requests (SEP-2322).
7 min read
Comparison
MCP vs A2A: what is the difference and when to use each
MCP and A2A solve different problems. MCP connects one agent down to its tools, data, and files. A2A connects one agent sideways to another agent so they can delegate work. Most real systems use both. Here is the difference and how to pick.
8 min read
Field notes
How to build an MCP server in Python
Build an MCP server in Python with the official mcp SDK: create a project with uv, make an MCPServer, decorate functions with @mcp.tool(), and run it over stdio. Full runnable code, tested on mcp 2.0.0 and Python 3.11.
8 min read
Tutorial
How to build an MCP client in TypeScript
Build a Model Context Protocol client in TypeScript: connect over stdio and Streamable HTTP, discover tools, call them, and read resources. Runnable code.
10 min read
Field notes
How to report progress from a long-running MCP tool
Report progress from a long-running MCP tool by having the client pass a progressToken and the server send notifications/progress updates as it works. Tested on the SDK.
7 min read
Tutorial
How to paginate results from an MCP tool
A tool that returns thousands of rows floods the model's context and breaks the call. Here is cursor-based pagination for an MCP tool: an opaque cursor, a server-capped page size, and typed structuredContent, tested end to end.
8 min read
Explainer
How many tools should an MCP server have?
Most MCP clients handle 15 to 20 tools well and stumble past 40. This covers why tool count hurts AI accuracy, and how to check a server's tools first.
6 min read
Tutorial
How to rate limit an MCP server (and handle 429s the right way)
Rate limiting is the top production failure mode for MCP servers in 2026. Here is a token-bucket limiter, a sliding-window variant, and the one rule that keeps agents stable: bubble the 429 back to the model, never retry inside the turn.
9 min read
Security
MCP token passthrough and the confused deputy problem
The 2026-07-28 MCP spec forbids passing a client's token through to upstream APIs and requires audience-bound tokens. Here is the anti-pattern and the fix.
10 min read
Field notes
How to handle errors in an MCP server
Handle errors in an MCP server by splitting them in two: return a tool result with isError true when the tool ran and failed, and a JSON-RPC error only when the request itself is invalid.
7 min read
Field notes
How to version an MCP server without breaking clients
Version an MCP server by keeping tool changes additive: add tools and optional fields, never rename, remove, or retype what clients already depend on.
7 min read
Explainer
How do you secure an MCP server against prompt injection?
Prompt injection can hijack an MCP server through tool descriptions and tool results, not just the user's typed message. Here is how to stop it.
7 min read
Comparison
MCP vs function calling: what is the difference and when to use each
MCP and function calling work at different layers. Function calling lets a model request a tool call; MCP is the protocol that exposes tools, resources, and prompts to any client. Here is how they differ and when to use each.
7 min read
Explainer
MCP transport: stdio vs Streamable HTTP (and when to use each)
MCP has two transports. Use stdio when the server runs as a local subprocess of one client, and Streamable HTTP when the server is a remote service many clients reach over the network. Here is the decision, with config for both.
7 min read
Tutorial
How to publish your MCP server to the MCP Registry
A tested, step-by-step guide to publishing an MCP server to the official MCP Registry: add mcpName to package.json, publish to npm, write server.json, and run mcp-publisher publish so clients and agents can discover it.
9 min read
Tutorial
How to add prompts to your MCP server
Add prompts to an MCP server with server.registerPrompt: give each one an argument schema and a handler that returns chat messages. Clients discover them with prompts/list and expand them with prompts/get. Runnable, tested code with argument autocompletion.
9 min read
MCP Tutorials
How to Serve Resources From an MCP Server
Expose read-only context from an MCP server with resources. Build a notes server using a fixed resource and a URI template, tested end to end on Node 25.
9 min read
Field notes
How to migrate MCP auth from DCR to CIMD
The 2026-07-28 MCP spec deprecates Dynamic Client Registration for Client ID Metadata Documents. Here is what changed and how to migrate your OAuth flow.
9 min read
Build-it
How to Test an MCP Server
Test an MCP server two ways: fast in-memory tests with Node's built-in test runner, and manual or CI checks with the MCP Inspector CLI. Full runnable code.
8 min read
Build-it
How to Deploy a Stateless MCP Server to Cloudflare Workers
Since the July 28, 2026 MCP spec dropped session IDs, a full MCP server fits in a single Cloudflare Workers fetch handler. Here is the handler, the wrangler.toml, and a verified deploy.
8 min read
Build-it
How to mark MCP tools read-only or destructive
MCP tool annotations (readOnlyHint, destructiveHint, and two more) tell a client which tools are safe to auto-run. Build-it, tested on Node 25 with the SDK.
8 min read
Tutorial
How to get MCP change notifications with subscriptions/listen
The 2026-07-28 MCP spec folds every change notification into one subscriptions/listen stream. Here is how it works, with runnable Node code you can test.
8 min read
Build-it
How to trace MCP requests with OpenTelemetry
The 2026-07-28 MCP spec carries W3C trace context in _meta, so MCP calls join one distributed trace instead of two orphans. Build-it, tested on Node 25.
9 min read
Tutorial
How to route MCP requests with Mcp-Method and Mcp-Name headers
The 2026-07-28 MCP spec requires Mcp-Method and Mcp-Name headers so gateways route MCP traffic without reading the body. Here is how, tested on Node 25.
9 min read
Tutorial
How to cache your MCP server's tool list (ttlMs and cacheScope, 2026-07-28 spec)
The 2026-07-28 MCP spec adds ttlMs and cacheScope to tools/list. Here's how to emit them from your server and honor them in a client, so clients stop re-polling your tool list on every turn. Tested TypeScript against @modelcontextprotocol/[email protected].
9 min read
Tutorial
How to return structured output from an MCP tool
Give an MCP tool an outputSchema and return structuredContent so the model gets typed JSON, not a string it has to re-parse. Runnable, tested code.
8 min read
Build-it
How to build an MCP server that wraps a REST API (stateless, 2026-07-28 spec)
Turn any REST API into an MCP server: one tool per endpoint, Zod-validated arguments, a shared HTTP client, and stateless Streamable HTTP so it runs behind a plain load balancer under the 2026-07-28 spec. Runnable TypeScript, no session store.
10 min read
Tutorial
How to make your MCP server ask the model to generate text (sampling is deprecated in the 2026-07-28 spec)
Sampling (sampling/createMessage) was deprecated on 2026-07-28. Here is the pattern that replaces it — a runnable MCP server that asks the model mid-tool using Multi Round-Trip Requests.
10 min read
Tutorial
How to get user input from an MCP tool call (2026-07-28 stateless elicitation)
How a tool asks the user for input in the 2026-07-28 MCP spec: return an InputRequiredResult from tools/call, then retry with inputResponses and an echoed requestState. No stream, no sessions.
9 min read
MCP Tutorials
How to build an MCP server that runs long tasks without timing out (Tasks extension)
A tested walkthrough of the MCP Tasks extension (2026-07-28 spec): return a task handle from tools/call, poll tasks/get, and stop blocking slow tools until they time out.
15 min read
MCP Tutorials
Build an MCP server that renders its own UI (MCP Apps extension)
Build an MCP App: an MCP tool that ships a sandboxed iframe UI via the MCP Apps extension (SEP-1865). Full tested code inlined, with a real wire trace.
14 min read
Tutorial
How to add OAuth 2.1 auth to a remote MCP server
Make your remote MCP server an OAuth 2.1 resource server: PRM discovery (RFC 9728), PKCE, and audience-bound tokens (RFC 8707), with runnable code.
12 min read
Field notes
Does Your MCP Server Need to Migrate Before July 28?
The MCP 2026-07-28 spec is the protocol's biggest revision, but backward compatibility means most servers don't have to migrate on day one. Here's how to tell which camp you're in.
5 min read
Build-it
How to make an MCP server stateless (2026-07-28 spec)
Make an MCP server stateless for the 2026-07-28 spec by setting the Streamable HTTP transport's sessionIdGenerator to undefined: drop sticky sessions, keep your tools.
9 min read
Explainer
MCP tools vs resources vs prompts: which to use
MCP tools are actions the model calls, resources are data the app feeds the model, and prompts are templates the user invokes. Choose by who is in control.
6 min read
Comparison
MCP vs traditional APIs: how it's different
MCP is a standard protocol for exposing tools and data to AI models; a traditional API is a bespoke interface your code calls. Here is when each one fits.
6 min read
Explainer
What is the Model Context Protocol (MCP)?
The Model Context Protocol (MCP) is an open standard that connects AI apps to external tools and data through one shared interface. Here is how it works.
6 min read
Engineering
How to build an MCP server that lets Claude query your Postgres database
A complete, runnable walkthrough: build a read-only MCP server that lets Claude answer questions about your Postgres data, with every file inline and versions pinned.
8 min read
