tf-mcp-server 0.11.0

MCP server for ToothFairyAI documentation and SDK operations

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
• 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
• 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

Variable	Default	Description
MCP_TRANSPORT	http	Transport type: stdio or http
MCP_HOST	0.0.0.0	Host to bind the server (HTTP mode only)
MCP_PORT	8000	Port to bind the server (HTTP mode only)
DOCS_PATH	docs/tf_docs/docs	Path to markdown documentation
API_DOCS_PATH	docs/api_docs/public	Path to API documentation
BASE_PATH	(auto-detected)	Base path to repository root

HTTP Endpoints

Endpoint	Method	Description
/sse	GET	SSE endpoint for MCP clients (Claude Code)
/health	GET	Health check for load balancers
/info	GET	Server information and stats

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:

Environment	Region	Endpoint	Status
Development	AU	https://mcp.toothfairylab.link/sse	✅ Available
Production	AU	https://mcp.toothfairyai.com/sse	✅ Available
Production	EU	https://mcp.eu.toothfairyai.com/sse	❌ Coming Soon
Production	US	https://mcp.us.toothfairyai.com/sse	❌ Coming Soon

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 105 tools organized into categories:

Category	Tools	Auth Required
Documentation	10	No
Release Notes	4	No
Public Utils	3	No
Agent Management	6	Yes
Agent Functions	5	Yes
Authorisations	5	Yes
Secrets	2	Yes
Documents	6	Yes
Entities	6	Yes
Folders	6	Yes
Chats	5	Yes
Prompts	5	Yes
Members	4	Yes
Channels	5	Yes
Connections	3	Yes
Benchmarks	5	Yes
Hooks	5	Yes
Scheduled Jobs	5	Yes
Sites	4	Yes
Dictionary	2	Yes
Request Logs	2	Yes
Settings	4	Yes
Billing	1	Yes
Embeddings	1	Yes

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

Model	Required Fields
AgentCreateModel	label, mode, interpolation_string (≥128 chars), goals, temperature, max_tokens, max_history, top_k, doc_top_k
AgentFunctionCreateModel	name, description, url
ScheduledJobCreateModel	name, agent_id, custom_prompt_id, schedule
DocumentCreateModel	user_id, title, doc_type
PromptCreateModel	user_id, label, prompt_type, interpolation_string
ConnectionCreateModel	name
FolderCreateModel	name (not label)
EntityCreateModel	user_id, label, entity_type
MemberCreateModel	user_id (not email)

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

Prompt	Description
api_usage_guide(endpoint)	Generate guide for an API endpoint
feature_guide(feature)	Generate guide for a feature
create_agent(agent_type, use_case)	Generate agent configuration

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