Practice: Agent architectures, agent frameworks and the Model Context Protocol
Generated by Claude through GigAI 0.1.11.10 on 2026-10-11.
Main tool: Model Context Protocol (MCP) · MCP is the open protocol that separates hosts, clients and servers, so one small server on a laptop lets you practise tool design, discovery, approval and authorization in the form any agent framework can consume. · Alternatives: Framework-native tool definitions in LangGraph or Pydantic AI (faster to start, but tied to one framework), provider-specific function calling (no shared server, every host re-implements the integration), plain REST with an OpenAPI description (mature auth and gateways, but no model-oriented discovery), and Temporal (durable execution for long runs, complementary rather than a tool protocol).
Every step links into the tool's own documentation; links were checked on 2026-10-11 · version 1
Setup (one time)
1. Install Node.js so you can launch the reference servers and the MCP Inspector from a package runner.
Most reference servers and the Inspector are distributed as Node packages, so this runtime is needed even if you write your own server in Python.
Explained in: Connect to local MCP servers - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: Asking Node for its version in a terminal prints a version number.
2. Choose one official SDK (Python or TypeScript) and note the install instructions for it.
Every later step uses one SDK to build a server, and staying with one language keeps the path short.
Explained in: SDKs - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: You have picked one SDK and can name its package and its repository.
3. Create a project directory with an isolated environment and add the MCP SDK as a dependency.
A dedicated environment with declared dependencies is what you will later pin and rebuild from scratch.
Explained in: Build an MCP server - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The project has a dependency file that lists the MCP SDK and the environment imports it without error.
4. Install the desktop host application the documentation uses, so you have a real host to connect servers to.
The host owns the model, the clients and the approval prompts, so you need one to see the protocol from the user side.
Explained in: Connect to local MCP servers - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The host application opens and shows its settings screen where servers are configured.
Steps
1. Run one of the reference servers as it is, without writing any code.
Seeing a working server first gives you a known-good baseline before you build your own.
Explained in: Example Servers - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The reference server process starts and stays running, waiting for a client.
2. Read the participants section and sketch which process on your laptop is the host, which is the client and which is the server.
The lesson's host, client and server split decides where permissions, connections and tools live, and one client connects to exactly one server.
Explained in: Architecture overview - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: You have a sketch labelling the host, one client per server, and each server, for the setup from the previous step.
3. Write your own server with two tools, each with a precise name, a description written for the model and typed parameters.
Tool design is mostly naming, descriptions and input schemas, because that is all the model sees when it decides what to call.
Explained in: Build an MCP server - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: Your server file defines two tools and loads without import or syntax errors.
4. Start your server and connect to it with the MCP Inspector, with server logs going to standard error.
The Inspector lets you exercise a server without a model in the loop, which is the fastest feedback cycle for tool work.
Explained in: Debugging - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The Inspector shows your server as connected and lists both of your tools.
5. Query the tool list and call one tool from the Inspector, then read the raw JSON-RPC request and response for each.
Discovery and execution are two separate exchanges, and reading the messages shows exactly what a host hands to the model.
Explained in: Architecture overview - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: You can point at the tools/list response with your schemas and at a tools/call response with your result.
6. Write an output schema for one tool, return structured content that matches it, and make a bad input return a tool error instead of crashing.
Structured results and clear errors let an agent recover in its loop rather than stall or hallucinate a result.
Explained in: Tools - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The Inspector shows structured content matching the schema for a good call and an error result for a bad one.
7. Create one prompt on your server that scripts a fixed sequence of steps, then compare it with letting the model pick tools freely for the same task.
A prompt the user invokes is a fixed workflow, while model-chosen tool calls are an agent loop, and seeing both side by side is the core distinction of the lesson.
Explained in: Understanding MCP servers - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: You have run the task both ways and written down where the sequence of calls differed.
8. Configure the filesystem server in the host with one allowed directory, trigger a write action, and deny it once before approving it.
Approval gates are enforced by the host, not the server, and you should see both the refusal path and the approved path.
Explained in: Connect to local MCP servers - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: The denied action left no file behind and the approved action created the file in the allowed directory.
9. Read the MCP Tasks section of the extensions overview and note how it relates to long-running work and how extensions are negotiated.
Durable, bounded runs need a way to track work that outlives one request, and you should know what the protocol offers before adding an external workflow engine.
Explained in: Extensions Overview - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: You can state in two sentences what the tasks extension is for and what your server would do when a client does not support it.
10. Package your server as an installable package and draft the registry metadata for it locally, without publishing anything.
A tool catalog is built from registry metadata that points at packages in ordinary package registries, so the two pieces must line up.
Explained in: The MCP Registry - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: A built package exists on disk and your draft metadata names that package and its version.
11. Reproduce the server from a clean checkout with pinned dependency versions and rerun your Inspector checks as a repeatable test pass.
A server that only works in your shell is not a platform component, and the same checks are what a CI job would run on every change.
Explained in: Debugging - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: A fresh environment built only from the pinned dependency file passes the same tool list and tool call checks.
12. Configure your server for HTTP transport protected by OAuth, using a local authorization server in a container in place of a paid identity provider, and walk the authorization flow.
Remote servers must validate tokens issued for them specifically, and this is the setup closest to what a shared production tool server looks like.
Explained in: Authorization - Model Context Protocol (modelcontextprotocol.io), checked 2026-10-11
Done when: A request without a token is rejected as unauthorized and a request with a token from your local authorization server succeeds.
Back to Agent architectures, agent frameworks and the Model Context Protocol