FastMCP 2.0 Hello World Server 🚀

A comprehensive example of building MCP servers with FastMCP 2.0 - the modern, Pythonic framework for Model Context Protocol servers.

🌟 Features

This server demonstrates FastMCP 2.0's key capabilities:

🛠️ Tools (Interactive Functions)

• say_hello(name) - Personalized greetings with timestamps
• add_numbers(a, b) - Integer addition with logging
• multiply_numbers(a, b) - Float multiplication with logging
• get_server_status() - Comprehensive server information

📚 Resources (Data Access)

• file://greeting/{name} - Dynamic personalized greeting resources
• file://info/server - Detailed server documentation
• file://help/math - Mathematical operations guide

🚀 Quick Start

Prerequisites

• Python 3.8+
• Docker Desktop
• Claude Desktop or Cursor IDE

Installation & Setup

1. Navigate to the project directory:

   cd /Users/maksymp/home_work/mcp/my_mcp/fastmcp_hello
   

2. Start the persistent server:

   cd server && docker build -t fastmcp-hello . && docker-compose up -d
   

3. Build the proxy image:

   cd proxy && docker build -t fastmcp-proxy .
   

🏗️ Architecture

This project uses a persistent server + ephemeral proxy architecture:

Claude Desktop → Docker Proxy (STDIO) → Persistent Server (HTTP/SSE)

Components:

• Persistent Server (server/): FastMCP server running in HTTP mode via Docker Compose
• Ephemeral Proxy (proxy/): STDIO-to-HTTP bridge that Claude Desktop runs on-demand
• Configurable Connection: Proxy can connect to local or remote servers

🔧 Configuration

Claude Desktop Integration

Current Setup (Recommended):

{
  "mcpServers": {
    "fastmcp-hello": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network", "host",
        "-e", "FASTMCP_SERVER_URL=http://localhost:8000/sse",
        "fastmcp-proxy"
      ]
    }
  }
}

Remote Server Connection

To connect to a remote FastMCP server, simply change the server URL:

{
  "mcpServers": {
    "remote-fastmcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network", "host",
        "-e", "FASTMCP_SERVER_URL=https://your-server.com:8000/sse",
        "fastmcp-proxy"
      ]
    }
  }
}

🐳 Docker Commands

Server Management

# Start persistent server
cd server
docker build -t fastmcp-hello . # if need to reassembly the server docker img
docker-compose up -d

# Check server status
docker-compose ps

# View server logs
docker-compose logs -f

# Stop server
docker-compose down

Proxy Management

# Build proxy image
cd proxy && docker build -t fastmcp-proxy .

# Test proxy manually
echo '{"jsonrpc": "2.0", "id": "test", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}' | docker run --rm -i --network host fastmcp-proxy

Health Checks

# Check server health (should return SSE stream)
curl http://localhost:8000/sse

💡 Usage Examples

Once connected to an LLM client (like Claude Desktop), you can interact with the server:

Tool Usage

> Say hello to Alice
"Hello, Alice! 👋 Welcome to FastMCP 2.0! (Generated at 2025-01-15 10:30:45)"

> Add 15 and 27
42

> Multiply 3.14 and 2
6.28

> Get server status
{comprehensive server information with capabilities and metadata}

Resource Access

> Get the file://greeting/Bob resource
# Personal Greeting for Bob
Welcome to FastMCP 2.0, Bob! 🎉
{personalized content with usage instructions}

> Show me the file://info/server resource
# FastMCP Hello Server Information
{detailed server documentation and capabilities}

> I need help with math operations (file://help/math resource)
# Mathematical Operations Help
{comprehensive guide to available math tools}

🏗️ Architecture

This server showcases FastMCP 2.0's elegant architecture:

from fastmcp import FastMCP

# Create server instance
mcp = FastMCP("Hello FastMCP 🚀")

# Define tools with simple decorators
@mcp.tool
def my_function(param: str) -> str:
    return f"Result: {param}"

# Define resources with URL patterns
@mcp.resource("data/{id}")
def my_resource(id: str) -> str:
    return f"Resource content for {id}"

# Run the server
mcp.run()

📖 FastMCP 2.0 Benefits

• 🚀 Fast: Minimal boilerplate, maximum productivity
• 🍀 Simple: Just decorate your functions - no complex setup
• 🐍 Pythonic: Natural Python development experience
• 🔍 Complete: Full MCP protocol support with modern features
• 🛡️ Type Safe: Automatic validation from type hints
• 📊 Observable: Built-in logging and debugging support

🔗 Learn More

• FastMCP Documentation: gofastmcp.com
• MCP Protocol: modelcontextprotocol.io
• FastMCP GitHub: github.com/jlowin/fastmcp

📝 License