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
77 posts
Explainer
What is an MCP client?
An MCP client is the part of an app that connects to one MCP server and calls what it offers. Here is how it fits into the Model Context Protocol.
5 min read
Tutorial
How do you add an MCP server to Claude Code?
Claude Code adds MCP servers with one command in your terminal. Here is the exact syntax for local and remote servers, plus the three connection scopes.
6 min read
Field notes
What happens when two MCP servers have the same tool name?
When two MCP servers publish a tool with the same name, most AI clients do not merge them cleanly. Here is what Claude Desktop, Cursor, and VS Code do.
6 min read
Field notes
Why does Claude Desktop say server disconnected?
Server disconnected means Claude Desktop's connection closed before setup finished. Here is why that happens and how to find the real cause fast.
6 min read
Field notes
MCP clients stopped following your redirects
Python MCP SDK 2.2.0 refuses any redirect that leaves your endpoint's origin. We probed 1,221 registry endpoints; at least six servers break on it.
9 min read
Field notes
How to serve Agent Skills over MCP
SEP-2640 went Final on 2026-09-13 and, as of 2026-09-18, no official SDK had merged it. Here is a working skills/list, skills/get and skill:// server on the released packages.
11 min read
Field notes
How many MCP servers are there?
We enumerated the official MCP Registry on 2026-09-05 and probed a random sample live: 26,837 servers listed, 862 of 1,500 answered, 1.9% of required arguments carry a value.
11 min read
Tutorial
How to add an MCP server to MCPOrbit
MCPOrbit has no config file to edit. Add a server in one form: a Name, a Type, then the program and its arguments in two fields, or a URL. No restarts.
7 min read
Field notes
How to add an MCP server to Cursor
Cursor loads MCP servers from one mcp.json file. The config is short. Two common things stop it starting, a relative path and a missing node binary, and both are fixable.
8 min read
Tutorial
How to add an MCP server to VS Code
VS Code reads MCP servers from .vscode/mcp.json under a servers key, not mcpServers. Set cwd or your server scans the wrong folder and never says so.
8 min read
Build it
How to build an MCP server for a GraphQL API
Do not hand the model a GraphQL query string. Introspect once, expose one typed tool per operation, and keep the selection set on the server.
11 min read
Tutorial
How to build an MCP server for a DuckDB database
Build a read-only MCP server over a DuckDB database in TypeScript. The read-only guard that is enough for SQLite leaks files and network on DuckDB. Here is the one setting that closes it, with runnable code.
12 min read
Tutorial
How to build an MCP server for MySQL
Build a read-only MySQL MCP server in one file, and fix the four mysql2 defaults that silently corrupt IDs, dates and blobs before a model sees them.
12 min read
Tutorial
How to build an MCP server for Redis
Expose Redis over MCP: read all five core types, page with SCAN instead of KEYS, and carry each key's TTL in the payload, because the protocol has no field for it.
12 min read
Field notes
How to build an MCP server in Go
Build an MCP server in Go with the official SDK: struct tags become the tool schema, and go build gives you one binary. Tested on go-sdk v1.7.0 and Go 1.27.
9 min read
Field notes
How to build an MCP server in Rust
Build an MCP server in Rust with the official rmcp SDK: derive your schemas, return Json for structured output, ship one 3.5 MB binary. Tested on rmcp 3.1.4.
9 min read
Tutorial
How to combine multiple MCP servers into one
Put several MCP servers behind one gateway: a server that is also a client, with prefixed tool names and a dead upstream contained. Runnable TypeScript.
10 min read
Field notes
How to debug an MCP server
A stray stdout line in a stdio MCP server usually does not crash it. It gets swallowed. Here is what really happens, and how to debug one properly.
9 min read
Tutorial
How to deploy an MCP server to AWS Lambda
Lambda can run an MCP server, but five things break before it does. Here are the measured failures and the one-file handler that fixes every one.
11 min read
Build-it
How to find out what an MCP client actually supports
Client docs and declared capabilities both mislead. Point the client at a small probe server, read the request log, and see which MCP methods it really sends.
9 min read
Build it
How to handle API keys in an MCP server
Keep API keys in the MCP server's environment, never in tool arguments or logs. A tested TypeScript walkthrough: fail-fast config, redaction, per-tenant keys.
9 min read
Field notes
How to handle timeouts in an MCP server
MCP timeouts belong to the client, not your server. Here is what the SDK does when a call times out, and why your handler keeps running after it.
10 min read
Field notes
Which URI Templates Work in MCP Resources
Eight of the ten URI template patterns we tested round-trip on MCP SDK 1.30.0. Two do not: one silently corrupts your variable, the other never matches at all.
8 min read
Comparison
MCP servers vs agent skills: when to use each
A skill is instructions loaded into the model's context. An MCP server is a process the model calls. Here is the decision rule, and why you want both.
9 min read
Tutorial
How to pass a file to an MCP tool
Three ways to get a file into an MCP tool: a path, inline base64, or a URL. Measured token costs for each, and the path guard that stops traversal.
11 min read
Tutorial
How to return an image from an MCP tool
Return an image from an MCP tool as a base64 image content block, or as a resource_link when the file is large. Runnable code and measured payload sizes.
9 min read
Field notes
How to run an MCP server in Docker
A stdio MCP server in Docker has no port. The client runs docker run -i and talks over the pipes. Here is the Dockerfile and the flags that break it.
10 min read
Field notes
What are MCP roots?
MCP roots let a client tell a server which folders it may use. The 2026-07-28 spec deprecates them, and roots/list fails before it reaches the wire on 2026-07-28 sessions.
8 min read
MCP Explainers
What Are MCP Server Instructions?
MCP server instructions are one optional string from the handshake. The SDK stores it and never acts on it. Whether the model sees it is the host's call.
9 min read
Field notes
Which language should you build an MCP server in?
We built the same MCP server in TypeScript, Python, Go and Rust, then measured startup, dependencies and binary size. The gaps are smaller than the cost of switching languages.
11 min read
Comparison
Where should you deploy an MCP server?
Since the 2026-07-28 spec removed protocol sessions, most MCP servers can run on plain serverless behind a round-robin load balancer. Three questions decide it: do you serve change notifications, how long does your slowest tool call run, and do you need per-user OAuth. Here is the decision, target by target.
9 min read
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. They compose rather than compete: A2A between the agents, MCP inside each. 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?
OpenAI caps tools at 128 but advises fewer than 20, and Claude Code degrades at 15 to 20. Aim for 5 to 15 per server, and 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 a common way MCP servers fall over in production. 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/sdk@1.30.0.
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 largest revision since launch, 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
