marcusotterstad/mcp-server-template

FastMCP HTTPS Server Template 🚀

Production-ready MCP server template using FastMCP 2.0. Direct HTTPS access - no proxies needed!

✨ Features

• FastMCP 2.0 - Latest MCP framework with HTTP transport
• Easy tool creation - Just add @mcp.tool decorated functions
• Railway ready - Automatic HTTPS with custom domains
• Direct HTTPS access - Works with Claude Code, APIs, and HTTP MCP clients
• AI-friendly - Auto-generates tool schemas from Python functions

🛠️ Built-in Tools

• hello_world(name) - Personalized greeting with server info
• get_server_info() - Detailed server information and status
• add_numbers(a, b) - Simple calculator example

🚀 Quick Start

1. Deploy to Railway

1. Fork this repo
2. Connect to Railway
3. Set environment variable: USER_ID=your-unique-id
4. Deploy! Your server will be at https://your-app.railway.app

2. Use with Claude Code

1. Open Claude Code
2. Add MCP server configuration:

   {
     "mcpServers": {
       "my-server": {
         "url": "https://your-app.railway.app",
         "transport": "http"
       }
     }
   }
   

3. Restart Claude Code and try: "Use the hello_world tool to greet me!"

3. Use with Custom Domain (Optional)

1. In Railway → Settings → Domains
2. Add your custom domain (e.g., my-mcp.yourdomain.com)
3. Railway provides automatic HTTPS certificates
4. Use your custom domain in MCP clients!

🔧 Adding New Tools

Creating new tools is super simple with FastMCP:

@mcp.tool
def your_new_tool(param1: str, param2: int) -> str:
    """
    Description of what your tool does.
    
    Args:
        param1: Description of parameter 1
        param2: Description of parameter 2
    
    Returns:
        Description of return value
    """
    # Your tool logic here
    return f"Result: {param1} with {param2}"

FastMCP automatically:

• ✅ Generates MCP tool schema from type hints
• ✅ Uses docstring for tool description
• ✅ Handles all protocol details
• ✅ Provides HTTP endpoints

📁 Project Structure

mcp-server-template/
├── server.py           # Main FastMCP HTTPS server
├── requirements.txt    # Python dependencies  
├── Dockerfile         # Railway deployment
└── README.md          # This file

🔍 Testing Your Server

Visit your Railway URL to see:

{
  "status": "running",
  "message": "FastMCP Server for user your-id is running!",
  "framework": "FastMCP 2.0",
  "tools_count": 3
}

Check available tools at /tools endpoint.

🌟 Why This Template?

• Production Ready - Built with FastMCP 2.0, the industry standard
• Direct HTTPS - No proxies, no local setup required
• Scalable - HTTP transport, auto-scaling containers
• Custom Domains - Use your own domain with automatic HTTPS
• Developer Friendly - Clear logging, error handling, health checks
• AI Compatible - Perfect for programmatic tool generation

🔗 HTTPS Setup

Railway automatically provides:

• ✅ Free HTTPS certificates - Your *.railway.app domain is secure
• ✅ Custom domain support - Add your own domain in Railway settings
• ✅ Automatic renewal - SSL certificates auto-renew
• ✅ Global CDN - Fast access worldwide

No domain setup required! Your Railway URL works immediately with HTTPS.

📚 Learn More

• FastMCP Documentation
• MCP Specification
• Railway Custom Domains

Ready to build amazing AI tools? Fork this repo and start adding your custom @mcp.tool functions! 🎉