AI

Most MCP servers get a handful of assert result == ... tests bolted on and nothing more. That misses the failures that actually bite: a tool quietly renamed, a parameter that changed type, a result that grew a field, an error that stopped being an error. A server is a contract a model depends on, and the contract needs its own tests. This tutorial builds a small, deterministic FastMCP server and then a layered test suite around it with four kinds of tests, each catching a different class of regression: ...

A command-line tool you already trust makes a good MCP tool: it has a stable interface, it is installed on the box, and its behavior is documented. The work is not reimplementing it, it is exposing it safely — mapping subcommands and flags to typed inputs, feeding untrusted input as data rather than shell, bounding runtime, and turning a non-zero exit into a clean tool error instead of a stack trace. ...

If you already run a FastAPI service, you do not have to hand-write an MCP tool for each endpoint or maintain a separate OpenAPI file. FastMCP.from_fastapi takes the app object itself, reads the schema FastAPI already generates, and mounts the app in-process: every operation becomes an MCP tool, resource, or resource template, and each call runs the real route handler with no network hop. The API stays the single source of truth for schemas, validation, and behavior. ...

If a service already publishes an OpenAPI spec, you do not have to hand-write a tool for each endpoint. FastMCP.from_openapi reads the spec and generates the whole server: every operation becomes an MCP tool, resource, or resource template, and each call is proxied to the real API through an HTTP client you supply. Point it at a spec, attach your auth, decide which routes to expose, and you have an MCP server. ...

Resources are the read side of MCP: addressable, cacheable data a client fetches by URI, separate from the tools that take action. Serving them well means more than returning a string. A resource has a MIME type, metadata a client shows in a picker, a choice between a fixed URI and a parameterized template, a text-or-binary body, and, for data that changes, a way to push updates instead of making clients poll. ...

Tools let a model do things; prompts let a user start things. An MCP prompt is a named, parameterized message template a client surfaces as a slash command or a menu entry — the user picks it, fills in a couple of arguments, and the client drops a ready-made conversation into the model. Most tutorials define one prompt in passing and move on. This one treats prompts as the subject. ...

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. ...