Posts

When a user fills in a prompt argument or a resource URI in an MCP client, the client can offer autocomplete, the same way a shell completes a path. That only works if the server answers a completion/complete request with suggestions scoped to what the user has typed. Without it, the user guesses at valid values and finds out they were wrong only when the call fails. This tutorial adds completions to a small documentation server built with FastMCP. One handler serves suggestions for a prompt’s arguments and a resource template’s parameters, filters by the typed prefix, reads from the same data the server actually serves, and narrows one argument based on another (topics depend on the chosen language). The stack is Mac-native: uv, make, and pytest. ...

Most MCP servers are static: a fixed set of tools and resources, decided at startup. Two features let a server change shape at runtime. Resource templates serve a whole family of resources from one parameterized URI, so book://1, book://2, and book://999 all resolve without registering a resource per book. list_changed notifications let the server tell a connected client that its tools, resources, or prompts have changed, so the client re-fetches instead of holding a stale list. ...

A working MCP tool is not the same as a well-designed one. A model decides whether to call your tool, and a client decides whether to auto-run it or ask the user first, based entirely on what the tool says about itself: its name, its description, its parameters, and its annotations. Get those wrong and a read-only lookup gets a confirmation prompt, a destructive delete runs silently, or the model picks the wrong tool. ...

A tool that returns only text makes every caller re-parse prose. The model reads "Denver is 21.5°C and clear" and has to extract the number again; a program has to write a regex. MCP’s structured output fixes this: a tool returns typed JSON in a structuredContent field, and advertises the shape up front as an output schema so callers know what to expect before they ever call it. This tutorial builds a small weather server with FastMCP whose tools return a Pydantic model, a nested collection, a bare primitive, and a hand-built result. You will see how FastMCP derives the output schema from a return-type annotation, fills in structuredContent automatically, validates every result against the schema, and how a client reads the typed value back. The stack is Mac-native: uv, make, and pytest. ...

Register a FastMCP Server with Claude Desktop and Claude Code wired a server into the two Claude clients. The AI-assisted code editors speak MCP too — VS Code (Copilot agent mode), Cursor, and Zed — and each keeps its config in a different file, under a different key, in a slightly different shape. This article takes one stdio FastMCP server and connects it to all three. VS Code Cursor Zed File .vscode/mcp.json (or user config) .cursor/mcp.json (or ~/.cursor/mcp.json) ~/.config/zed/settings.json Top-level key servers mcpServers context_servers Entry shape type + command/args (or url) command/args (or url) command/args/env (or url/headers) Scope workspace and user project and global global only Two things are common to all three, and to the Claude clients before them: ...

Two earlier articles bookend this one. Package and Distribute a FastMCP Server as a uvx Tool gets you to uvx macmcp in your own terminal, and Register a FastMCP Server with Claude Desktop and Claude Code wires a server into clients, but launches it from a local path or git+https. This closes the loop: publish the package to PyPI once, and from then on anyone — and any MCP client — runs it with uvx <name>, no clone, no virtualenv, no path. ...

This is the Go companion to Build an MCP Server in TypeScript with the Official SDK. It builds the same kind of server — two tools and a resource — with the official Go SDK (github.com/modelcontextprotocol/go-sdk), served over the stdio transport so a local client launches it as a subprocess. The result is a single compiled binary with no runtime beyond itself. The project uses the cmd/ + internal/ layout, a Makefile, and Go’s built-in testing. ...

The FastMCP tutorials in this series are Python, and FastMCP wraps the Model Context Protocol so you rarely touch it directly. This article drops down a level and builds the same kind of server with the official TypeScript SDK (@modelcontextprotocol/sdk) — the reference implementation Anthropic maintains. You register tools and resources on an McpServer, connect it to the stdio transport, and a local client launches it as a subprocess. The stack is Node, tsc, and vitest. ...

The FastMCP tutorials in this series deploy to a Mac with launchd: one machine, your machine, awake and on the network. This one takes the opposite approach and deploys an MCP server to Cloudflare Workers — TypeScript with the Agents SDK’s McpAgent, pushed to a public HTTPS URL that runs in data centers worldwide. There is no server of your own to keep running, and per-session state lives in a Durable Object (SQLite) instead of a file on disk. ...

A server in production has to answer three questions: is it up, what is it doing, and when something breaks, why. This tutorial adds the three observability pillars to a FastMCP server — structured logs, a health check, and metrics — using only the standard library plus two FastMCP primitives (middleware and custom routes). The stack is Mac-native: uv, make, and pytest. The design keeps instrumentation out of the tools: Logging is a JSON formatter on the root logger, written to stderr. Metrics are a small in-process registry fed by one piece of middleware, so every tool is measured without touching its code. Health and metrics are exposed twice: as MCP resources (readable over any transport, including stdio) and as HTTP routes (/health, /metrics) for load balancers and Prometheus. The stdio trap. The stdio transport uses stdout for the MCP protocol itself. Anything else written to stdout — a stray print, a log line — corrupts the stream and breaks the client. All logging here goes to stderr, which is safe on both transports. This is the single most common way a working server mysteriously fails once a client connects to it over stdio. ...