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:

  1. Learn the core MCP architecture (Host / Client / Server, Tools / Resources / Prompts);
  2. Run a ready-made MCP server with a single command;
  3. Write your own MCP server in Python from scratch and connect it to Claude Code and Cursor;
  4. 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
2
3
pip install "mcp[cli]"
# or with uv:
uv add "mcp[cli]"

Create time_server.py:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
from mcp.server.fastmcp import FastMCP
import datetime

# Create the server; its name shows up in the client
mcp = FastMCP("TimeServer")


# The decorator turns a plain function into an AI-callable Tool
@mcp.tool()
def current_time(timezone: str = "UTC") -> str:
"""Return the current time in the given timezone. Examples: Asia/Shanghai, UTC, America/New_York."""
from zoneinfo import ZoneInfo
try:
now = datetime.datetime.now(ZoneInfo(timezone))
return f"Current time in {timezone}: {now:%Y-%m-%d %H:%M:%S}"
except Exception as e:
return f"Could not parse timezone {timezone}: {e}"


@mcp.tool()
def add(a: float, b: float) -> float:
"""Add two numbers and return the sum."""
return a + b


if __name__ == "__main__":
mcp.run() # stdio transport by default

Three habits to note:

  1. The function name IS the tool name — use clear lowercase snake_case;
  2. 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;
  3. Type annotations drive the parameter schema — timezone: str becomes 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
2
3
4
5
6
7
8
{
"mcpServers": {
"time-server": {
"command": "python",
"args": ["/path/to/time_server.py"]
}
}
}

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 + args in 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("NoteServer")
notes = {} # in-memory; replace with a file/database for production


@mcp.tool()
def save_note(key: str, content: str) -> str:
"""Save a note. key is the note name, content is the text."""
notes[key] = content
return f"Saved note {key}"


@mcp.tool()
def get_note(key: str) -> str:
"""Read a note by key; say clearly when it doesn't exist."""
return notes.get(key, f"No note found for {key}")


if __name__ == "__main__":
mcp.run()

Now register a resource so the AI automatically gets background context in relevant conversations:

1
2
3
4
@mcp.resource("config://app")
def get_config() -> str:
"""App config, automatically visible to the AI when relevant."""
return "App: DemoApp; Version: 1.0; Languages: English/Chinese"

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:

  1. Least privilege: expose only the directories/capabilities needed — never hand a bare os.system to the agent;
  2. 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);
  3. 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.resource to 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!