gh-jezweb-claude-skills-skills-fastmcp/references/cloud-deployment.md

FastMCP Cloud Deployment Guide

Complete guide for deploying FastMCP servers to FastMCP Cloud.

Critical Requirements

❗️ MUST HAVE for FastMCP Cloud:

1. Module-level server object named mcp, server, or app
2. PyPI dependencies only in requirements.txt
3. Public GitHub repository (or accessible to FastMCP Cloud)
4. Environment variables for configuration (no hardcoded secrets)

Cloud-Ready Server Pattern

# server.py
from fastmcp import FastMCP
import os

# ✅ CORRECT: Module-level export
mcp = FastMCP("production-server")

# ✅ Use environment variables
API_KEY = os.getenv("API_KEY")
DATABASE_URL = os.getenv("DATABASE_URL")

@mcp.tool()
async def production_tool(data: str) -> dict:
    if not API_KEY:
        return {"error": "API_KEY not configured"}
    return {"status": "success", "data": data}

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

Common Anti-Patterns

❌ WRONG: Function-Wrapped Server

def create_server():
    mcp = FastMCP("server")
    return mcp

if __name__ == "__main__":
    server = create_server()  # Too late for cloud!
    server.run()

✅ CORRECT: Factory with Module Export

def create_server() -> FastMCP:
    mcp = FastMCP("server")
    # Complex setup logic here
    return mcp

# Export at module level
mcp = create_server()

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

Deployment Steps

1. Prepare Repository

# Initialize git
git init

# Add files
git add .

# Commit
git commit -m "Initial MCP server"

# Create GitHub repo
gh repo create my-mcp-server --public

# Push
git push -u origin main

2. Deploy to FastMCP Cloud

1. Visit https://fastmcp.cloud
2. Sign in with GitHub
3. Click "Create Project"
4. Select your repository
5. Configure:
   • Server Name: Your project name
   • Entrypoint: server.py
   • Environment Variables: Add all needed variables

3. Configure Environment Variables

In FastMCP Cloud dashboard, add:

• API_KEY
• DATABASE_URL
• CACHE_TTL
• Any custom variables

4. Access Your Server

• URL: https://your-project.fastmcp.app/mcp
• Auto-deploy: Pushes to main branch auto-deploy
• PR Previews: Pull requests get preview deployments

Project Structure Requirements

Minimal Structure

my-mcp-server/
├── server.py          # Main entry point (required)
├── requirements.txt   # PyPI dependencies (required)
├── .env              # Local dev only (git-ignored)
├── .gitignore        # Must ignore .env
└── README.md         # Documentation (recommended)

Production Structure

my-mcp-server/
├── src/
│   ├── server.py         # Main entry point
│   ├── utils.py          # Self-contained utilities
│   └── tools/           # Tool modules
│       ├── __init__.py
│       └── api_tools.py
├── requirements.txt
├── .env.example         # Template for .env
├── .gitignore
└── README.md

Requirements.txt Rules

✅ ALLOWED: PyPI Packages

fastmcp>=2.12.0
httpx>=0.27.0
python-dotenv>=1.0.0
pydantic>=2.0.0

❌ NOT ALLOWED: Non-PyPI Dependencies

# Don't use these in cloud:
git+https://github.com/user/repo.git
-e ./local-package
./wheels/package.whl

Environment Variables Best Practices

✅ GOOD: Environment-based Configuration

import os

class Config:
    API_KEY = os.getenv("API_KEY", "")
    BASE_URL = os.getenv("BASE_URL", "https://api.example.com")
    DEBUG = os.getenv("DEBUG", "false").lower() == "true"

    @classmethod
    def validate(cls):
        if not cls.API_KEY:
            raise ValueError("API_KEY is required")

❌ BAD: Hardcoded Values

# Never do this in cloud:
API_KEY = "sk-1234567890"  # Exposed in repository!
DATABASE_URL = "postgresql://user:pass@host/db"  # Insecure!

Avoiding Circular Imports

Critical for cloud deployment!

❌ WRONG: Factory Function in __init__.py

# shared/__init__.py
def get_api_client():
    from .api_client import APIClient  # Circular import risk
    return APIClient()

# shared/monitoring.py
from . import get_api_client  # Creates circle!

✅ CORRECT: Direct Imports

# shared/__init__.py
from .api_client import APIClient
from .cache import CacheManager

# shared/monitoring.py
from .api_client import APIClient
client = APIClient()  # Create directly

Testing Before Deployment

Local Testing

# Test with stdio (default)
fastmcp dev server.py

# Test with HTTP
python server.py --transport http --port 8000

Pre-Deployment Checklist

• Server object exported at module level
• Only PyPI dependencies in requirements.txt
• No hardcoded secrets (all in environment variables)
• .env file in .gitignore
• No circular imports
• No import-time async execution
• Works with fastmcp dev server.py
• Git repository committed and pushed
• All required environment variables documented

Monitoring Deployment

Check Deployment Logs

FastMCP Cloud provides:

• Build logs
• Runtime logs
• Error logs

Health Check Endpoint

Add a health check resource:

@mcp.resource("health://status")
async def health_check() -> dict:
    return {
        "status": "healthy",
        "timestamp": datetime.now().isoformat(),
        "version": "1.0.0"
    }

Common Deployment Errors

1. "No server object found"

   • Fix: Export server at module level

2. "Module not found"

   • Fix: Use only PyPI packages

3. "Import error: circular dependency"

   • Fix: Avoid factory functions in __init__.py

4. "Environment variable not set"

   • Fix: Add variables in FastMCP Cloud dashboard

Continuous Deployment

FastMCP Cloud automatically deploys when you push to main:

# Make changes
git add .
git commit -m "Add new feature"
git push

# Deployment happens automatically!
# Check status at fastmcp.cloud

Rollback Strategy

If deployment fails:

# Revert to previous commit
git revert HEAD
git push

# Or reset to specific commit
git reset --hard <commit-hash>
git push --force  # Use with caution!

Resources

• FastMCP Cloud: https://fastmcp.cloud
• FastMCP GitHub: https://github.com/jlowin/fastmcp
• Deployment Docs: Check FastMCP Cloud documentation