graphiti/mcp_server/docs/FASTMCP_CLOUD_DEPLOYMENT.md

FastMCP Cloud Deployment Guide

This guide covers deploying the Graphiti MCP server to FastMCP Cloud, a managed hosting platform for MCP servers.

Overview

FastMCP Cloud is a managed platform that:

• Automatically builds and deploys your MCP server from GitHub
• Provides a unique HTTPS URL for your server
• Handles SSL certificates and authentication
• Auto-redeploys on pushes to main branch
• Creates preview deployments for pull requests

Note: FastMCP Cloud is currently free while in beta.

Prerequisites

Before deploying to FastMCP Cloud, you need:

1. GitHub Account - FastMCP Cloud integrates with GitHub repos
2. Cloud Database - Neo4j Aura or FalkorDB Cloud (must be internet-accessible)
3. API Keys - OpenAI (required), Anthropic (optional)
4. Verified Repo - Run the verification script first

Pre-Deployment Verification

Run the verification script to check your server is ready:

cd mcp_server
uv run python scripts/verify_fastmcp_cloud_readiness.py

This checks:

• Server is discoverable via fastmcp inspect
• Dependencies are properly declared in pyproject.toml
• Environment variables are documented
• No secrets are committed to git
• Server can be imported successfully
• Entrypoint format is correct

All checks should pass before deploying.

Deployment Steps

Step 0: Validate Your Server Locally

Before deploying to FastMCP Cloud, validate with BOTH static and runtime checks.

Static Validation: fastmcp inspect

Checks that your server module can be imported and tools are registered:

cd mcp_server
uv run fastmcp inspect src/graphiti_mcp_server.py:mcp

Expected successful output:

Name: Graphiti Agent Memory
Version: <version>
Tools: 9 found
  - add_memory: Add an episode to memory
  - search_nodes: Search for nodes in the graph memory
  - search_memory_facts: Search the graph memory for relevant facts
  - get_episodes: Get episodes from the graph memory
  - get_entity_edge: Get an entity edge from the graph memory by its UUID
  - delete_episode: Delete an episode from the graph memory
  - delete_entity_edge: Delete an entity edge from the graph memory
  - clear_graph: Clear all data from the graph for specified group IDs
  - get_status: Get the status of the Graphiti MCP server

Runtime Validation: fastmcp dev (ESSENTIAL!)

The inspect command only checks imports - it does NOT catch runtime initialization issues.

Run the interactive inspector to test actual server initialization:

cd mcp_server
uv run fastmcp dev src/graphiti_mcp_server.py:mcp

This starts your server and opens an interactive web UI at http://localhost:6274.

Critical test in the web UI:

1. Open http://localhost:6274 in your browser
2. Click the "get_status" tool
3. Click "Execute"
4. Expected: {"status": "ok", "message": "Graphiti MCP server is running and connected to Neo4j database"}
5. If you see: {"status": "error", "message": "Graphiti service not initialized"} - DO NOT DEPLOY

Step 1: Set Up Cloud Database

Option A: Neo4j Aura (Recommended for Neo4j users)

1. Visit Neo4j Aura
2. Create a free instance
3. Note your connection details:
   • URI: neo4j+s://xxxxx.databases.neo4j.io
   • Username: neo4j
   • Password: (generated)

Option B: FalkorDB Cloud

1. Visit FalkorDB Cloud
2. Create an instance
3. Note your connection details:
   • URI: redis://username:password@host:port
   • Database: default_db

Important: Local databases (localhost) will NOT work with FastMCP Cloud. You must use a cloud-hosted database.

Step 2: Prepare Your Repository

1. Ensure pyproject.toml is complete

   FastMCP Cloud automatically detects dependencies from pyproject.toml:

   [project]
   dependencies = [
       "fastmcp>=2.13.3",
       "graphiti-core[falkordb]>=0.23.1",
       "pydantic>=2.0.0",
       "pydantic-settings>=2.0.0",
       "python-dotenv>=1.0.0",
       # ... other dependencies
   ]
   

2. Verify .env is in .gitignore

   git check-ignore -v .env
   # Should output: .gitignore:XX:.env    .env
   

3. Commit and push your code

   git add .
   git commit -m "Prepare for FastMCP Cloud deployment"
   git push origin main
   

Step 3: Create FastMCP Cloud Project

1. Visit fastmcp.cloud

2. Sign in with your GitHub account

3. Create a new project:

   • Click "Create Project"
   • Select your repository
   • Repository can be public or private

4. Configure project settings:

   Setting	Value	Notes
   Name	graphiti-mcp	Used in your deployment URL
   Entrypoint	mcp_server/src/graphiti_mcp_server.py:mcp	Points to module-level server instance
   Authentication	Enabled	Recommended for production

   Important: The entrypoint must point to a module-level FastMCP instance.

Step 4: Configure Environment Variables

Set these environment variables in the FastMCP Cloud UI (NOT in .env files):

For Neo4j:

# Required
OPENAI_API_KEY=sk-...
NEO4J_URI=neo4j+s://xxxxx.databases.neo4j.io
NEO4J_USER=neo4j
NEO4J_PASSWORD=your-password
DATABASE_PROVIDER=neo4j

# Optional
SEMAPHORE_LIMIT=10
GRAPHITI_GROUP_ID=main

For FalkorDB:

# Required
OPENAI_API_KEY=sk-...
FALKORDB_URI=redis://host:port
FALKORDB_USER=your-username
FALKORDB_PASSWORD=your-password
FALKORDB_DATABASE=default_db
DATABASE_PROVIDER=falkordb

# Optional
SEMAPHORE_LIMIT=10
GRAPHITI_GROUP_ID=main

Security Note: Environment variables set in FastMCP Cloud UI are encrypted at rest and never logged.

Step 5: Deploy

1. Click "Deploy"

   FastMCP Cloud will:

   1. Clone your repository
   2. Detect dependencies from pyproject.toml
   3. Install dependencies using uv
   4. Build your FastMCP server
   5. Deploy to a unique URL
   6. Make it immediately available

2. Monitor the build

   Watch the build logs in the FastMCP Cloud UI. The build typically takes 2-5 minutes.

3. Note your deployment URL

   Your server will be accessible at:

   https://your-project-name.fastmcp.app/mcp
   

Step 6: Verify Deployment

1. Test with fastmcp inspect

   fastmcp inspect https://your-project-name.fastmcp.app/mcp
   

   You should see your server info and 9 tools.

2. Connect from Claude Desktop

   FastMCP Cloud provides auto-generated configuration. Click "Connect" in the UI and copy the configuration.

3. Test add_memory tool

   Use Claude Desktop or an MCP client to test:

   Add a memory: "John prefers dark mode UI"
   

Configuration Differences

FastMCP Cloud vs Local Development

Aspect	FastMCP Cloud	Local Development
Entry point	Module-level instance only	if __name__ == "__main__" runs
Dependencies	Auto-detected from pyproject.toml	Installed via uv sync
Environment	Set in Cloud UI	Loaded from .env file
Transport	Managed by platform	Configured via CLI args
HTTPS	Automatic	Manual setup
Authentication	Built-in OAuth	Configure manually

What Gets Ignored

FastMCP Cloud ignores:

• if __name__ == "__main__" blocks
• .env files (use Cloud UI instead)
• fastmcp.json config files (use Cloud UI)
• YAML config files (use environment variables)
• Docker configurations
• CLI arguments

FastMCP Cloud uses:

• Module-level FastMCP instance (mcp = FastMCP(...))
• pyproject.toml or requirements.txt
• Environment variables from Cloud UI
• Code from your main branch

Troubleshooting

Build Failures

Issue: Dependencies fail to install

Solution:
1. Verify pyproject.toml syntax
2. Check dependency versions are available on PyPI
3. Remove any local-only dependencies (like editable installs)
4. Check that python-dotenv is included

Issue: Module import errors

Solution:
1. Ensure all imports use relative paths from src/
2. Check that config/, models/, etc. have __init__.py files
3. Verify the entrypoint format: mcp_server/src/graphiti_mcp_server.py:mcp

Runtime Errors

Issue: "API key is not configured"

Solution:
1. Verify environment variables are set in FastMCP Cloud UI
2. Check variable names match exactly (case-sensitive)
3. Redeploy after adding environment variables

Issue: Database connection failures

Solution:
1. Verify database is internet-accessible (not localhost!)
2. Check credentials are correct
3. For Neo4j Aura: Use neo4j+s:// protocol
4. For FalkorDB: Check firewall allows FastMCP Cloud IPs

Issue: 429 Rate Limit Errors

Solution:
1. Lower SEMAPHORE_LIMIT based on your API tier:
   - OpenAI Tier 1: SEMAPHORE_LIMIT=1-2
   - OpenAI Tier 2: SEMAPHORE_LIMIT=5-8
   - OpenAI Tier 3: SEMAPHORE_LIMIT=10-15

Issue: "Graphiti service not initialized"

Solution:
1. This means initialization failed silently
2. Check database credentials
3. Check LLM API key
4. Run fastmcp dev locally to debug

Best Practices

1. Use Environment Variables

All configuration should use environment variables:

# Good - FastMCP Cloud compatible
import os
api_key = os.environ.get('OPENAI_API_KEY')

# Bad - Won't work on FastMCP Cloud
api_key = 'sk-hardcoded-key'

2. Module-Level Server Instance

# Good - FastMCP Cloud can discover this
from fastmcp import FastMCP
mcp = FastMCP("Graphiti Agent Memory")

if __name__ == "__main__":
    # This block is IGNORED by FastMCP Cloud
    mcp.run()

3. Test Locally First

Always test locally before deploying:

# Run verification script
cd mcp_server
uv run python scripts/verify_fastmcp_cloud_readiness.py

# Test with fastmcp dev
uv run fastmcp dev src/graphiti_mcp_server.py:mcp

4. Monitor Resource Usage

• Neo4j Aura free tier: Limited connections
• FalkorDB free tier: 100 MB limit
• OpenAI rate limits: Tier-dependent
• SEMAPHORE_LIMIT: Tune based on API tier

Security Considerations

Secrets Management

• DO: Set secrets in FastMCP Cloud UI
• DO: Add .env to .gitignore
• DO: Use .env.example for documentation
• DON'T: Commit .env files
• DON'T: Hardcode API keys
• DON'T: Store secrets in YAML configs

Authentication

FastMCP Cloud provides built-in authentication:

• Enabled: Only org members can connect (recommended)
• Disabled: Public access (use for demos only)

Enable authentication for production deployments.

Summary Checklist

Before deploying to FastMCP Cloud:

• Run uv run python scripts/verify_fastmcp_cloud_readiness.py
• All checks pass
• Cloud database is running (Neo4j Aura or FalkorDB Cloud)
• API keys are ready (OpenAI required)
• Code is pushed to GitHub main branch
• .env is in .gitignore
• No secrets committed to repo

During deployment:

• Create project on fastmcp.cloud
• Configure entrypoint: mcp_server/src/graphiti_mcp_server.py:mcp
• Enable authentication
• Set all required environment variables in UI
• Deploy and monitor build logs

After deployment:

• Test with fastmcp inspect <URL>
• Connect from Claude Desktop
• Test add_memory and search tools
• Monitor database usage
• Monitor API rate limits

Resources

• FastMCP Cloud: fastmcp.cloud
• FastMCP Docs: gofastmcp.com
• FastMCP Discord: discord.com/invite/aGsSC3yDF4
• Neo4j Aura: neo4j.com/cloud/aura
• FalkorDB Cloud: cloud.falkordb.com
• Verification Script: scripts/verify_fastmcp_cloud_readiness.py

You're now ready to deploy!