Practice: Building Model Context Protocol (MCP) servers
Generated by Claude through GigAI 0.1.11.10 on 2026-10-11.
Main tool: Model Context Protocol (MCP) · MCP is the open standard the lesson teaches, so building a server against its own documentation practises the contract of tools, resources, prompts, lifecycle and authorization that every compliant host understands. · Alternatives: Framework-specific tool definitions such as LangChain or LlamaIndex tools (quick to write but tied to one agent framework), plain function calling against an OpenAPI-described REST API (reuses existing APIs but has no shared discovery or lifecycle), and agent-to-agent protocols such as A2A (connect whole agents to each other, not systems to one agent).
Every step links into the tool's own documentation; links were checked on 2026-10-11 · version 1
Setup (one time)
1. Choose the SDK you will build with; the Python SDK is the default for this path and the TypeScript SDK is the alternative.
Every later step uses one SDK's way of declaring tools, resources and prompts. Choosing once keeps the path consistent.
Explained in: SDKs - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: You can name the SDK you chose and its language runtime is the one you will install next.
2. Install the language runtime and the package manager that the server quickstart lists for your SDK.
The quickstart assumes specific minimum versions. A mismatch shows up later as confusing import or startup errors.
Explained in: Build an MCP server - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The runtime and the package manager each print a version that meets the stated minimum.
3. Create the project folder, the virtual environment and the dependencies as the quickstart describes.
An isolated project with declared dependencies is what a host will launch later, and what a teammate needs to rebuild your server.
Explained in: Build an MCP server - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The project folder holds a dependency file, an activated environment and an empty server file.
4. Install Claude Desktop as the local host application; it runs on a laptop with no GPU and no cloud deployment.
A server is only useful when a host runs a client against it. You need a real host to see discovery and tool approval from the user's side.
Explained in: Connect to local MCP servers - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The host application opens and you can find its settings for local servers.
Steps
1. Write the server instance and one tool with typed arguments and a clear description, following the quickstart.
This is the core of building a server with an SDK. The SDK turns your function signature and description into the tool definition a model reads.
Explained in: Build an MCP server - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The server file defines a named server and at least one tool whose arguments and description you wrote yourself.
2. Run the server over the stdio transport and keep everything except protocol messages off standard output.
A first run proves the server starts and waits for a client. On stdio, any stray print corrupts the JSON-RPC stream.
Explained in: Build an MCP server - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The process starts without an error and stays running, waiting for input, with nothing printed to standard output.
3. Read the participants section and label the host, the client and the server in your own setup.
The trust boundary of a deployment follows these three roles. One host runs one client per server, which is why servers stay isolated from each other.
Explained in: Architecture overview - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: You can say which process on your laptop is the host, which is the client and which is the server.
4. Write out by hand the initialize request, the initialize response and the initialized notification that your server would exchange with a client.
The lifecycle begins with version and capability negotiation. Knowing these three messages lets you diagnose a connection that never reaches the operation phase.
Explained in: Lifecycle - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: Your three JSON-RPC messages carry a protocol version, the capabilities of each side and the correct method names, matching the section.
5. Create a resource on your server that exposes read-only data by URI, plus one resource template with a parameter.
Resources are context the application chooses to attach, not actions the model takes. Separating them from tools keeps the contract clear.
Explained in: Understanding MCP servers - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The server declares one fixed resource and one templated resource, each with a URI, a name and a content type.
6. Create a prompt on your server that takes one argument and returns a reusable message template for a common workflow.
Prompts are the user-controlled primitive. They let a customer's team ship a vetted way of invoking your tools and resources.
Explained in: Understanding MCP servers - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The server declares a named prompt with a described argument that returns at least one message.
7. Write a failing case for your tool and return it as a tool execution error, as distinct from a protocol error.
A model can recover from an execution error it can read, but not from a broken protocol exchange. This distinction shapes how agents behave on bad input.
Explained in: Tools - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: Calling the tool with bad input yields a result flagged as an error with a readable message, and the server keeps running.
8. Write a small client that launches your server over stdio, initializes a session and lists its tools; save the listing, add a tool, then compare a second listing against it. Skip the chat loop, which needs a paid model API key.
A saved capability listing is the server's contract in a form you can compare. Diffing it between versions shows exactly what changed for every host.
Explained in: Build an MCP client - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The client prints your tool names, and the second saved listing differs from the first only by the tool you added.
9. Configure Claude Desktop to launch your server by registering its command and absolute path in the host's server configuration.
Registering the server with a host is how it gets handed to users. It also shows how the host presents your tools and asks for approval.
Explained in: Build an MCP server - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: After a restart the host lists your server's tools, and a tool call you approve returns a result in the conversation.
10. Read the deployment paths section and decide whether your server ships as a local stdio process or as a remote HTTP service.
The transport decides who runs the server, where credentials live and whether authorization is required. That is the main deployment decision for a customer.
Explained in: Build with Agent Skills - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: You can state which path fits your server and one consequence of that choice for the customer's security review.
11. Reproduce a startup failure by breaking the configured server path, find the cause in the host's logs, then restore the path.
Most field problems are launch and environment problems. A repeatable way to read the logs turns a silent failure into a short fix.
Explained in: Debugging - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: You can point to the log line that shows the failed launch, and the server connects again once the path is restored.
12. Write the authorization plan for an HTTP version of your server, covering the authorization server, the resource identifier used as token audience and the rule for rejecting tokens issued for another resource. A real deployment needs a hosted authorization server; a local one in a container is the closest substitute.
A remote server is a protected resource that must accept only tokens issued for it. Passing a client's token through to other services creates a confused deputy.
Explained in: Authorization - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: Your one-page plan names the audience value your server validates and states that it never forwards a client's token to an upstream service.