Yesterday was setup. Today we wrote a working MCP server, tested it, and plugged it into a real agent — then spent the back half on the thing nobody warns you about: versioning.
1. Two SDKs, One Direction
- The official Anthropic Python SDK is what we’re using. It already includes FastMCP 1.0 — that’s the ergonomic API you’ll be writing against.
- FastMCP 2.0 is a separate, independently developed project that went further on its own.
Both are open source. Start with the official SDK; you’ll recognise FastMCP’s style when you meet it.
2. The Three Building Blocks
| Block | What it is |
|---|---|
| Tools | Actions. The model triggers them, they can change state — book a ticket, write a file |
| Resources | Read-only data. Exposed to the host, not actions |
| Prompts | Reusable templates showing how to work with this server |
A server can expose any combination. In practice tools are what an agent calls to get something done, so that’s where we started.
3. Writing the Server
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("hello-mcp")
@mcp.tool()
def add(a: float, b: float) -> float:
"""Add two numbers and return the result."""
return a + b
@mcp.tool()
def modulus(a: float, b: float) -> float:
"""Return the remainder of a divided by b."""
return a % b
if __name__ == "__main__":
mcp.run()@mcp.tool()turns a plain function into an MCP tool.- No name in the decorator? The function name is used.
- Type hints and the docstring are the contract the model reads. Same rule as every tool we’ve written this course.
We built add, subtract, multiply and modulus.
4. Testing with the Inspector
uv run mcp dev server.pyThis opens the MCP Inspector in a browser — call each tool, see the arguments and the response.
- Requires Node.js, which is why yesterday’s setup mattered.
- It hot-reloads, so you can iterate quickly.
- It’s a developer tool, not an agent. Passing here means your tools work; it says nothing about whether a model will choose them.
5. Wiring It into Claude Desktop
Developer settings → edit claude_desktop_config.json → add your server under mcpServers:
{
"mcpServers": {
"hello-mcp": {
"command": "C:\\Users\\you\\.local\\bin\\uv.exe",
"args": ["run", "--directory", "C:\\path\\to\\learning-mcp", "server.py"]
}
}
}Everything that went wrong today, and how to avoid it:
| Symptom | Cause |
|---|---|
| Config won’t load at all | A trailing comma in the JSON. JSON doesn’t allow them |
| “Server connection closed unexpectedly” | Check the developer logs — they name the real error |
| “server.py not found” | Wrong working directory. Pass --directory, or use absolute paths |
| Changes have no effect | Claude Desktop must be fully quit and restarted. On Windows, exit from the system tray — closing the window isn’t enough |
Finding your uv path on Windows: use where.exe uv or Get-Command uv in PowerShell. Plain where is an alias for Where-Object and won’t do what you expect.
Windows paths in JSON need escaped backslashes (C:\\Users\\...). Forward slashes also work. Mac and Linux need neither.
6. Other Clients
VS Code with GitHub Copilot does the same job with a different key — servers rather than mcpServers. Most agents use JSON config; each has its own syntax. Read that client’s docs rather than copying a Claude config across.
7. What uv Actually Is
A package and environment manager written in Rust — pip’s job, done much faster. If you’ve used Composer in PHP or npm in Node, it occupies the same slot in your workflow.
8. Versioning: The Part That Bites in Production
An MCP server is a plugin. It bridges to an external service, so if that service is down, your server runs and still fails. Design for that.
Agents run on demand, not 24/7. They’re restarted often, which is why config drift matters less here than in always-on systems — but it’s also why a new tool isn’t visible until the agent restarts and rediscovers the definitions.
Adding a tool is safe. It’s like adding a sixth page to a five-page site: nothing existing breaks.
Changing a contract is not.
A recharge tool takes three arguments: number, provider, plan. You add a fourth — payment mode — and make it mandatory. Every agent that hasn’t reloaded still sends three. The tool now fails every single time.
Make new parameters optional, with a sensible default (payment mode defaults to UPI). Old callers keep working; new ones get the feature. Backward compatibility is the ground rule.
Whose job is the config? The server developer owns the tool. The agent operator owns the JSON. A mismatch throws an error that your code should handle gracefully — and production config files belong only in authorised hands.
✅ Action Items
- Get your server running in Claude Desktop on your own machine, with your own paths.
- Fix the working-directory problem yourself — it’s the most instructive bug in this session.
- Read the developer logs when something fails. Guessing is slower.
- Try the same server in a second client, such as VS Code with Copilot, and notice what changes in the config.
⏭️ Next up: beyond tools — resources and prompts, and servers that reach real external services.
