Hello World MCP Server 👋

A minimal MCP (Model Context Protocol) server in Python, built to learn the basics. It exposes the three MCP primitives:

• Tools — say_hello, add, current_time (functions the AI calls)
• Resources — info://server, greeting://{name} (data the AI reads)
• Prompt — daily_briefing (a reusable template the user invokes)

This guide lets you replicate the whole thing from scratch.

---

1. What is MCP? (the 30-second version)

MCP is an open standard that lets AI apps connect to external tools and data in a consistent way — like a USB-C port for AI.

You (plain English) ──► Claude Code ──► [JSON-RPC over stdio] ──► your server
                        (the host)                                (the tools)

• Host — the AI app you talk to (Claude Code).
• Server — the program you write that exposes capabilities.
• Tool — a function the AI can call (e.g. say_hello).
• stdio — the transport: Claude Code launches your server as a subprocess and talks to it via standard input/output using JSON-RPC messages.

⚠️ Key idea: you never type into the server directly. You talk to Claude Code in plain English, and it decides to call your tools.

---

2. Prerequisites

• uv — Python package/project manager. (Handles Python versions for you — even if your system Python is old.)
• The MCP Python SDK needs Python 3.10+; uv installs a compatible one automatically.

---

3. Set up the project

mkdir hello-mcp && cd hello-mcp

# Create a uv project pinned to Python 3.11
uv init --name hello-mcp --python 3.11 .

# Install the MCP SDK (with CLI extras like the Inspector)
uv add "mcp[cli]"

# uv creates a placeholder main.py — remove it, we use server.py
rm main.py

---

4. Write the server

Create server.py:

from datetime import datetime
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError

from mcp.server.fastmcp import FastMCP

# The name shows up in the host when it lists servers.
mcp = FastMCP("hello-mcp")


@mcp.tool()
def say_hello(name: str = "world") -> str:
    """Return a friendly greeting for the given name."""
    return f"Hello, {name}! 👋 This came from your MCP server."


@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b


@mcp.tool()
def current_time(timezone: str = "UTC") -> str:
    """Return the current date and time for an IANA timezone
    (e.g. 'America/Lima', 'Asia/Tokyo'). Defaults to UTC."""
    try:
        tz = ZoneInfo(timezone)
    except ZoneInfoNotFoundError:
        return f"Unknown timezone: {timezone!r}. Use an IANA name like 'America/Lima'."
    now = datetime.now(tz)
    return now.strftime("%Y-%m-%d %H:%M:%S %Z")


if __name__ == "__main__":
    # Talk to the host over stdio (server runs as a local subprocess).
    mcp.run(transport="stdio")

What each part does

Part	Why it matters
FastMCP("hello-mcp")	Creates the server. The name identifies it in the host.
@mcp.tool()	Registers a function as a callable tool.
Type hints (name: str, a: int)	Become the tool's input schema — the AI knows what arguments to send.
Docstring ("""...""")	Tells the AI when and how to use the tool. Examples help a lot — e.g. mentioning 'Asia/Tokyo' lets Claude map "Tokyo" → the right value.
Default values (= "world")	Make arguments optional.
try/except in current_time	Returns a friendly message instead of crashing on bad input.
mcp.run(transport="stdio")	Starts the server speaking JSON-RPC over stdio.

---

5. Verify it works (before connecting)

# Does it import cleanly?
uv run python -c "import server; print('OK')"

# Test a tool function directly
uv run python -c "import server; print(server.current_time('Asia/Tokyo'))"

---

6. Register it with Claude Code

claude mcp add hello-mcp -- uv --directory /ABSOLUTE/PATH/TO/hello-mcp run server.py

• Use the absolute path to your project so it works from anywhere.
• Check it's healthy:

claude mcp list
# → hello-mcp: ... - ✓ Connected

---

7. Use it

1. Reload the VSCode window (Cmd+Shift+P → "Reload Window") so Claude Code picks up the server.
2. Ask Claude Code in plain English:
   • "Use the say_hello tool to greet Dani."
   • "Add 2 and 3."
   • "What time is it in Madrid?"

Claude discovers the tools, calls them, and uses the results in its answer.

---

8. The dev loop (whenever you change the server)

edit server.py  →  reload the VSCode window  →  the new/updated tool appears

The server is loaded at session start, so changes need a reload (or restart) to take effect.

---

9. Add a resource

A resource is readable data identified by a URI — think of it as a GET endpoint, while a tool is a POST. The key difference is who drives it:

	Tool	Resource
Initiated by	the AI decides to call it	the user/host attaches it to the chat
Analogy	POST endpoint (do something)	GET endpoint (read something)
Example	add(2, 3)	greeting://Dani

# Static resource — fixed URI, fixed-ish content.
@mcp.resource("info://server")
def server_info() -> str:
    """Static facts about this server."""
    return "hello-mcp v0.1.0 ..."


# Resource TEMPLATE — {name} in the URI becomes a function argument.
@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """A personalized greeting."""
    return f"¡Hola, {name}!"

The URI scheme (info://, greeting://) is yours to invent — it just needs to be a valid URI. In the Inspector, check the Resources tab to read them.

---

10. Add a prompt

A prompt is a reusable message template. Unlike tools (AI-driven) and resources (data), prompts are user-driven: hosts surface them as slash commands or menu items, the user picks one and fills the arguments, and the returned text is sent to the AI as if the user typed it.

@mcp.prompt()
def daily_briefing(name: str, timezone: str = "America/Lima") -> str:
    """Kick off a personalized briefing that exercises the server's tools."""
    return (
        f"Please greet {name} using the say_hello tool, then use current_time "
        f"to report the time in {timezone}, and finish with one fun fact "
        f"about that part of the world."
    )

In Claude Code, MCP prompts appear as slash commands named /mcp__<server>__<prompt>. In the Inspector, use the Prompts tab.

The three primitives, side by side

Primitive	Who triggers it	Shape	This server
Tool	the AI (model)	function call with typed args	say_hello, add, current_time
Resource	the user / host app	read-only data at a URI	info://server, greeting://{name}
Prompt	the user	message template → conversation starter	daily_briefing

---

10.5 Test resources & prompts in Claude Code ✅ (verified)

After editing server.py, reload the VSCode window first — the host snapshots the server at session start (section 8).

Resources

• Type @ in the chat input — MCP resources show up in the mention picker; attaching one sends its content as context.
• Or just ask: "read the resource info://server" / "read greeting://Dani" — Claude has a built-in tool for resources/read.

Prompts

MCP prompts become slash commands with inline, space-separated, positional arguments (no form UI here — that's a Claude Desktop thing):

/mcp__hello-mcp__daily_briefing Dani Asia/Tokyo
                                 │     └─ timezone (optional, has a default)
                                 └─ name (required)

What happens: the server renders the template → it's sent as your message → Claude reads it and calls say_hello and current_time to fulfill it. One command exercises the prompt and the tools.

Gotcha	Cause & fix
Missing required argument: name	Arguments are inline and positional — append them after the command. Args with spaces aren't supported in this UI.
Unknown command: /hello-mcp:daily_briefing	Wrong name format. The canonical form is /mcp__hello-mcp__daily_briefing (use autocomplete).

---

11. Test in other hosts

The whole point of MCP: the same server works in any host. Here's how to connect this one to three different AI apps.

A. Claude Desktop ✅ (verified)

📖 Full walkthrough with every gotcha: docs/claude-desktop.md

1. Install from https://claude.ai/download and sign in.

2. Edit the config file (create it if missing): ~/Library/Application Support/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "hello-mcp": {
         "command": "uv",
         "args": ["--directory", "/Users/chocodani/dev/mcp", "run", "server.py"]
       }
     }
   }
   

   If Claude Desktop can't find uv, use its absolute path (which uv → e.g. /opt/homebrew/bin/uv).

3. Fully quit (Cmd+Q) and reopen Claude Desktop.

4. Test each primitive:

   • Tools — ask "What time is it in Lima?" (look for the 🔨 / connectors icon).
   • Resources — click + → search for the server name → attach info://server.
   • Prompt — click + → choose daily_briefing, fill in the arguments.

B. Gemini CLI ✅ (verified)

📖 Full walkthrough with every gotcha: docs/gemini-cli.md

1. Install and sign in with your Google account:

   npm install -g @google/gemini-cli
   gemini   # first run opens the login flow
   

2. Register the server in ~/.gemini/settings.json (user-wide) — same shape as Claude Desktop's config:

   {
     "mcpServers": {
       "hello-mcp": {
         "command": "uv",
         "args": ["--directory", "/Users/chocodani/dev/mcp", "run", "server.py"]
       }
     }
   }
   

3. Run gemini, then check /mcp — it lists the server and its tools.
4. Test: ask "add 2 and 40"; the prompt appears as the slash command /daily_briefing.

C. ChatGPT (GPT)

ChatGPT cannot launch local stdio servers — it's a web app, so it needs a public HTTP URL. That's why server.py supports a second transport:

uv run server.py --http   # serves at http://localhost:8000/mcp

1. Start the server with --http (leave it running).
2. Expose it to the internet with a tunnel:

   brew install ngrok        # one-time; needs a free ngrok account + authtoken
   ngrok http 8000           # gives you https://<random>.ngrok-free.app
   

3. In ChatGPT: Settings → Apps & Connectors → Advanced → Developer mode (requires a paid plan), then Create a connector with URL https://<random>.ngrok-free.app/mcp and no authentication.
4. In a new chat, enable the connector via the + menu and ask it to greet you or add numbers.

⚠️ While the tunnel is up, anyone with the URL can call your server — fine for a hello-world, but remember it for real servers (MCP uses OAuth for this). Stop ngrok when you're done.

💡 Stdio vs HTTP — same server, same tools; only the transport changes. Local hosts (Claude Code/Desktop, Gemini CLI) spawn the process and speak stdio; remote hosts (ChatGPT) speak HTTP to a URL.

Note: host support for the primitives varies — every host supports tools, but resources/prompts UI differs (e.g. Gemini CLI exposes prompts as slash commands but has no resource picker).

---

Common gotchas

Symptom	Cause & fix
Invalid JSON: expected value... errors	You typed English/shell commands into a manually-run server.py. Don't run it by hand — let Claude Code launch it. Just talk to Claude.
New tool doesn't show up	Reload the VSCode window after editing.
Tools unavailable mid-session	The server disconnected — reload the window to reconnect.
claude mcp list shows nothing	Run it in a normal terminal, not inside a running server.py.

---

Optional: visual debugging with the MCP Inspector

The MCP Inspector is the official dev tool for MCP servers — think Postman for MCP. Instead of wiring the server into Claude Code to test it, you connect the Inspector directly, call tools by hand, and watch the raw JSON-RPC traffic. Great for iterating on server.py without touching your Claude Code config.

Launch it

# Starts your server AND opens the Inspector web UI in your browser
uv run mcp dev server.py

This spawns the server over stdio and prints a local URL (e.g. http://localhost:5173). Open it if the browser doesn't open automatically.

Equivalent without uv: npx @modelcontextprotocol/inspector uv --directory . run server.py

Connect

In the left panel, the transport is STDIO and the command/args are already filled in. Click Connect — the status should turn green.

Invoke the tools

1. Open the Tools tab → click List Tools. You'll see say_hello, add, and current_time.
2. Click a tool, fill in the form, and hit Run Tool. The result appears on the right; expand the JSON view to see the raw tools/call request/response.

Tool	Input	Result
say_hello	name = Dani	Hello, Dani! 👋 This came from your MCP server.
say_hello	(blank)	Hello, world! 👋 ... (uses the default)
add	a = 2, b = 40	42
current_time	timezone = America/Lima	e.g. 2026-06-10 12:34:56 -05
current_time	(blank)	current UTC time
current_time	timezone = Mars/Phobos	Unknown timezone: 'Mars/Phobos'. Use an IANA name...

Dev loop with the Inspector

edit server.py  →  click "Restart" (or reconnect) in the Inspector  →  re-run the tool

No VSCode reload needed — the Inspector manages the server process itself.

---

Project structure

hello-mcp/
├── server.py        ← your MCP server (3 tools, 2 resources, 1 prompt)
├── docs/
│   ├── claude-desktop.md  ← guide: connect the server to Claude Desktop
│   └── gemini-cli.md      ← guide: connect the server to Gemini CLI
├── pyproject.toml   ← project + mcp[cli] dependency
├── .python-version  ← pins Python 3.11
├── uv.lock          ← locked dependency versions
├── README.md        ← this guide
└── .venv/           ← virtual environment (managed by uv)

---

Where to go next

• Add a resource ✅ done (section 9)
• Add a prompt ✅ done (section 10)
• Test in other hosts ✅ done (section 11)
• Add authentication — protect an HTTP server with OAuth.
• Use real data — wrap an API or database in tools/resources.
• Async tools — async def works too, for I/O-bound work.

📚 Official docs: https://modelcontextprotocol.io