AI Tutorial · October 16, 2026 - AI Practical Guide
2026-10-16 AI Tutorial: Give Your AI Agent Hands — Build Your First MCP Server From Scratch
Background
In 2026, large models are no longer “chatbots.” From StepFun’s STEPX Neo phone with system-level tool calls, to DeepSeek Harness’s “everything is a plugin,” to Claude Code rewriting your codebase — an agent is only as useful as the tools it can call.
But how do you connect tools? The era of one SDK per model vendor and one plugin spec per app is over. The MCP (Model Context Protocol), introduced by Anthropic in late 2024, has become the de facto standard for giving AI access to the outside world — a unified interface often described as the “USB-C for AI.”
In this tutorial you will:
- Learn the core MCP architecture (Host / Client / Server, Tools / Resources / Prompts);
- Run a ready-made MCP server with a single command;
- Write your own MCP server in Python from scratch and connect it to Claude Code and Cursor;
- Pick up debugging and security essentials.
No GPU needed — just a computer with Python.
Prerequisites
Software
- Python 3.10+ (check:
python3 --version) - Node.js 18+ (optional, for the official example servers; check:
node -v) - uv (optional but recommended — faster Python package management):
curl -LsSf https://astral.sh/uv/install.sh | sh - An MCP-capable client: Claude Code (
npm install -g @anthropic-ai/claude-code) or Cursor
The Core Concepts in 3 Minutes
MCP is a client-server architecture with four roles:
| Role | What it does | Analogy |
|---|---|---|
| Host | The app the user faces (Claude Code, Cursor, Claude Desktop) | Your computer |
| Client | The component inside the Host that talks to one Server | A USB port |
| Server | A program exposing tools, resources, and prompts (local or remote) | A USB drive / peripheral |
| Transport | How they communicate: stdio (local process) or Streamable HTTP (remote) | The cable |
A server can expose three kinds of capabilities:
- Tools — executable functions (check weather, read/write files, call APIs). The agent’s “hands”;
- Resources — read-only data (documents, database records). The agent’s “reference library”;
- Prompts — reusable prompt templates. The agent’s “operation manual.”
This tutorial focuses on the most-used one: Tools.
Steps
1. Run a Ready-Made MCP Server (Official Example)
No code yet — feel what a “tool” feels like. Start the official filesystem server with npx:
1 | npx -y @modelcontextprotocol/server-filesystem /tmp |
This launches a stdio process exposing /tmp to an AI. Right now it’s idling — no Host is attached yet. We’ll attach one soon.
Want to explore? Run
npx -y @modelcontextprotocol/server-everything— it demonstrates all three capability types (Tools, Resources, Prompts) in idiomatic form and doubles as reference code.
2. Write Your First Server with FastMCP
FastMCP is the official Python framework — a tool in a few lines. Install:
1 | pip install "mcp[cli]" |
Create time_server.py:
1 | from mcp.server.fastmcp import FastMCP |
Three habits to note:
- The function name IS the tool name — use clear lowercase snake_case;
- The docstring is the instructions for the AI — the more specific you are (parameter meaning, example values), the more accurate the model’s calls. This is the single most important MCP developer habit;
- Type annotations drive the parameter schema —
timezone: strbecomes JSON Schema automatically, telling the model what to send.
3. Test Locally First: MCP Inspector
Running python time_server.py directly just hangs — in stdio mode the process waits for a client. Verify with the official debugger:
1 | npx -y @modelcontextprotocol/inspector python time_server.py |
Open http://localhost:6274 in your browser:
- The left panel lists the server’s tools (
current_time,add); - Click a tool to fill parameters and invoke it manually, watching the result;
- This beats “shove it into an AI and guess” — make sure the tool is correct before wiring it up.
4. Connect It to Claude Code
Claude Code registers a local MCP server with one command:
1 | claude mcp add time-server -- python /path/to/time_server.py |
Check registration:
1 | claude mcp list |
Then ask inside Claude Code:
1 | What time is it in Shanghai? Use the time-server. |
Watch the model “call the tool” before answering — it parses Asia/Shanghai and invokes it itself. On errors, claude mcp remove time-server and re-add.
5. Connect It to Cursor
Cursor uses a project-level config file. Create .cursor/mcp.json at your project root:
1 | { |
Open Settings → MCP in Cursor — time-server and its tools should appear. If not, hit refresh or restart Cursor. Type /mcp in a chat to view and toggle tools.
Other MCP clients (Claude Desktop, Windsurf, VS Code Copilot, …) follow the exact same pattern: point
command + argsin a settings file or GUI.
6. Level Up: Stateful Tools and Resources
Tools don’t have to be stateless. A practical example — a notes server so the AI can remember across conversations:
1 | from mcp.server.fastmcp import FastMCP |
Now register a resource so the AI automatically gets background context in relevant conversations:
1 |
|
Refresh in Inspector or your client — a new Resource appears. The model reads it automatically when relevant, no explicit call needed.
7. Debugging Cheat Sheet
| Symptom | Likely cause | Fix |
|---|---|---|
| Client says server connection failed | Wrong path / missing deps | Run python time_server.py in a terminal first to confirm it starts |
| Tool called but errored | Docstring doesn’t match implementation | Test manually in Inspector, fix, then rewire |
| Parameters always wrong | Unclear type annotations | Add defaults and concrete examples (timezone: str = "UTC") |
| stdio process exits immediately | Crashes on startup | Read stderr: python time_server.py 2>&1 |
| Model “pretends” to call but nothing happens | Stateless server or wrong path | Confirm the tool really executes (add a print, watch logs) |
8. Security Red Lines (Important)
An MCP server’s power equals the permissions you give it. The official server-filesystem can only touch /tmp because that’s what you exposed; your own tool that runs commands really runs commands. Three iron rules:
- Least privilege: expose only the directories/capabilities needed — never hand a bare
os.systemto the agent; - Beware prompt injection: web pages or files a tool returns can smuggle instructions — external content must never steer your agent (Anthropic was already debating “how to safely deploy tools that execute code” in internal docs in 2021 — still the #1 risk today);
- Authenticate remote servers: when deploying over Streamable HTTP, add an API key / OAuth, or your tools are naked on the public internet.
Summary
You’ve walked a complete MCP development path:
- Understood the Host / Client / Server architecture and the Tools / Resources / Prompts capabilities;
- Ran an official example server with one npx command;
- Wrote your own tools with FastMCP in a dozen lines (plus stateful and resource-backed variants);
- Verified locally with Inspector, then wired everything into Claude Code and Cursor;
- Got a debugging cheat sheet and a security checklist.
Next steps:
- Connect your server to real APIs: weather, exchange rates, SQLite queries (SQLite is a perfect practice target);
- Use
@mcp.resourceto feed project docs to the agent — a team knowledge base; - Deploy a remote MCP server (Streamable HTTP + auth) so many machines and colleagues share one tool set;
- Study
server-everything‘s source for official best practices.
The value of MCP: write a tool once, and every agent in the world can use it. From today, your AI doesn’t just talk — it does.
Happy hacking!






