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.

Related MCP server: mcpscope

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

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:

# 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

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.

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

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.

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