ToothFairyAI Documentation MCP Server

A Model Context Protocol (MCP) server that exposes ToothFairyAI documentation, API specifications, and full SDK operations for AI assistants.

Features

• Documentation Resources: Access 47+ markdown documentation pages, plus TF Code and TF Design docs loaded as separate resource roots (toothfairy://tfcode/*, toothfairy://tfdesign/*)
• API Specifications: OpenAPI specs for Platform, AI Services, and Voice APIs
• Full-Text Search: Search across all documentation and API endpoints
• Dual Transport Support: Run as HTTP server (remote) or stdio (local)
• SDK Integration: 85+ tools for full workspace management
• Cross-Workspace Migration: install_toothfairy_cli + migrate_toothfairy_agents wrap the @toothfairyai/cli migrate command to copy agents and dependent resources (hooks, functions, authorisations, …) between workspaces. See the migrate-agents skill.
• Validation Models: Pre-validate payloads with Pydantic models before API calls
• Health Checks: Built-in /health and /info endpoints (HTTP mode)

Quick Start

Local Development (stdio Mode)

For use with local MCP clients like Claude Code or Claude Desktop:

cd tf_mcp_server
python -m venv venv
source venv/bin/activate
pip install -e .

# Run with stdio transport
python -m tf_mcp_server.server --stdio

Local Development (SSE Mode)

For testing SSE transport locally:

cd tf_mcp_server
source venv/bin/activate

# Run with SSE transport (default)
python -m tf_mcp_server.server

# Server available at http://localhost:8000/sse

Docker Deployment

# From repository root
docker build -t tf-mcp-server -f tf_mcp_server/Dockerfile.full .
docker run -p 8000:8000 tf-mcp-server

Environment Variables

HTTP Endpoints

Health Check Response

{
  "status": "healthy",
  "server": "ToothFairyAI Documentation MCP",
  "docs_loaded": 47,
  "api_specs_loaded": 3
}

Connecting MCP Clients

Claude Code (CLI) Configuration

To use the ToothFairyAI MCP server with Claude Code:

Option 1: Local stdio (Recommended for development)

Run the server locally using stdio transport for the most reliable connection:

CLI Command

claude mcp add toothfairy-docs -- python -m tf_mcp_server.server --stdio

Manual configuration

Edit your Claude config file (~/.claude.json):

{
  "mcpServers": {
    "toothfairy-docs": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "tf_mcp_server.server", "--stdio"],
      "cwd": "/path/to/tooth-fairy-website-1/tf_mcp_server"
    }
  }
}

Option 2: Remote SSE

Connect to the hosted remote server using SSE:

CLI Command (example for AU production)

claude mcp add toothfairy-docs "https://mcp.toothfairyai.com/sse" -t sse

Manual configuration

{
  "mcpServers": {
    "toothfairy-docs": {
      "type": "sse",
      "url": "https://mcp.toothfairyai.com/sse"
    }
  }
}

Note: Use type: "sse" for Server-Sent Events transport.

Verify the connection

claude mcp list

Or within Claude Code, type /mcp to see connected servers.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Local stdio

{
  "mcpServers": {
    "toothfairy-docs": {
      "command": "python",
      "args": ["-m", "tf_mcp_server.server", "--stdio"],
      "cwd": "/path/to/tooth-fairy-website-1/tf_mcp_server"
    }
  }
}

Remote SSE

{
  "mcpServers": {
    "toothfairy-docs": {
      "url": "https://mcp.toothfairyai.com/sse",
      "transport": "sse"
    }
  }
}

Connection Reliability

Built-in Keepalive

The MCP server uses FastMCP which includes automatic SSE pings every 15 seconds to keep connections alive. This should prevent most idle timeout issues.

Why Connections May Still Disconnect

If you experience disconnections (e.g., after ~60 minutes), the cause is likely:

1. AWS ALB idle timeout - Default 60s, max configurable 4000s (~66 min)
2. ALB target group settings - Connection draining may close idle connections
3. Proxy buffering - Nginx/CloudFront may buffer SSE responses

AWS ALB Configuration (Critical for Production)

To prevent disconnections, configure the ALB with these settings:

Load Balancer Attributes:

idle_timeout.timeout_seconds = 3600  # 1 hour (or higher if needed)

Target Group Settings:

deregistration_delay.timeout_seconds = 300
slow_start.duration_seconds = 0

Listener Rules (if using nginx as reverse proxy):

location / {
    proxy_pass http://ecs-target;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_set_header Host $host;
    
    # CRITICAL: Disable buffering for SSE
    proxy_buffering off;
    proxy_cache off;
    
    # Long timeouts matching ALB idle timeout
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

Nginx Configuration (for self-hosting)

If deploying behind nginx, use these settings for optimal SSE support:

location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_set_header Host $host;
    
    # Critical for SSE streaming - disables buffering
    proxy_buffering off;
    proxy_cache off;
    
    # Match your ALB idle timeout
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

MCP Tools

This server provides 108 tools organized into categories:

See TOOLS.md for complete tool documentation.

Validation Models

The MCP server uses Pydantic validation models from the ToothFairyAI Python SDK to pre-validate payloads before making API calls. This prevents common errors like:

• Missing required fields (e.g., interpolation_string for agents, custom_prompt_id for scheduled jobs)
• Invalid field values (e.g., interpolation_string must be ≥ 128 characters)
• Type mismatches and invalid enum values

Available Validation Models

Using Validation in MCP Tools

The MCP tools automatically validate payloads using these models. When validation fails, you'll receive a clear error message:

ValidationError: interpolation_string must be at least 128 characters

For direct SDK usage:

from toothfairyai.models import AgentCreateModel

agent_data = AgentCreateModel(
    label="Support Agent",
    mode="retriever",
    interpolation_string="You are a helpful assistant..." * 10,  # Min 128 chars
    goals="Help customers",
    temperature=0.7,
    max_tokens=2000,
    max_history=10,
    top_k=10,
    doc_top_k=5
)

MCP Resources

Documentation

• toothfairy://docs/list - List all documentation pages
• toothfairy://docs/{category}/{slug} - Get a specific doc page

API Specifications

• toothfairy://api/list - List all API specs
• toothfairy://api/{name} - Get OpenAPI spec (platform, ai-services, voice)
• toothfairy://api/{name}/endpoints - Get endpoints summary
• toothfairy://api/integration-guide - Voice API integration guide

MCP Prompts

AWS ECS Deployment (Production)

Deployment is automated via GitHub Actions. The workflow triggers on pushes to development branch when changes are made to:

• tf_mcp_server/**
• docs/tf_docs/docs/**
• docs/api_docs/public/**

GitHub Actions Workflow

See: .github/workflows/deployMcpServer-dev.yml

Management Commands

cd tf_mcp_server/aws
./deploy.sh status   # Get service status and endpoint URL
./deploy.sh logs     # View live logs
./deploy.sh destroy  # Delete all resources

Programmatic Access

from mcp import ClientSession
from mcp.client.sse import sse_client

# Use available endpoint
async with sse_client(url="https://mcp.toothfairyai.com/sse") as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        result = await session.call_tool("search_docs", {"query": "agents"})

References

• FastMCP Documentation
• MCP Specification
• AWS MCP Servers
• FastMCP HTTP Deployment

License

MIT