MCP Integration

Loading version...

ToothFairyAI provides a comprehensive Model Context Protocol (MCP) server that enables seamless integration with AI assistants, development tools, and automation workflows. The MCP server gives you programmatic access to documentation, API specifications, release notes, and full workspace management capabilities with 105 tools across 24 categories.

Quick Reference

Resource	URL
Health Check	https://mcp.toothfairyai.com/health
Server Info	https://mcp.toothfairyai.com/info
SSE Endpoint	https://mcp.toothfairyai.com/sse
Tool Reference	Tool Reference Page

Getting Started

Available Endpoints

Connect to the hosted MCP server using Server-Sent Events (SSE). Choose the endpoint based on your location and environment:

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

Client Configuration

Connect to the ToothFairyAI MCP server using the remote SSE endpoint. No installation required.

Claude Desktop

Add to your Claude Desktop configuration file:

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

Claude Code

Use the CLI to add the MCP server:

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

Zed Editor

Add to your Zed settings.json (Command Palette → "zed: open settings"):

{
  "context_servers": {
    "toothfairy-docs": {
      "url": "https://mcp.toothfairyai.com/sse"
    }
  }
}

Zed Tool Usage

Some models work better with MCP tools when you mention the server by name. Try prompts like "use toothfairy-docs to search for..." for best results.

Cursor

Add to your Cursor MCP settings:

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

Gemini CLI

Add to ~/.gemini/settings.json:

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

Usage:

> @toothfairy-docs Search for agent creation documentation
> @toothfairy-docs Get the latest release notes

ChatGPT / OpenAI

ChatGPT MCP Support

ChatGPT (web and desktop apps) does not natively support MCP servers. OpenAI uses a different plugin/GPT architecture.

Alternatives for OpenAI users:

• Use the ToothFairyAI Python SDK directly: pip install toothfairyai
• Build a custom GPT that calls ToothFairyAI APIs
• Use the API Integration endpoints directly

Local Installation (Offline/Air-Gapped)

For environments requiring offline access or enhanced security, install the MCP server locally:

pip install tf-mcp-server

Then configure your client to use stdio transport instead of SSE:

Client	Local stdio Configuration
Zed	{"context_servers": {"toothfairy-docs": {"command": "tf-mcp-server", "args": ["--stdio"]}}}
Gemini CLI	{"mcpServers": {"toothfairy-docs": {"command": "tf-mcp-server", "args": ["--stdio"]}}}
Claude Desktop	{"mcpServers": {"toothfairy-docs": {"command": "tf-mcp-server", "args": ["--stdio"]}}}

When to Use Local Installation

• Air-gapped or offline environments
• Strict security requirements prohibiting external connections
• Development and testing of MCP server modifications
• Environments with unreliable internet connectivity

Architecture Overview

Connection Reliability

Built-in Keepalive

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

Why Connections May Disconnect

If you experience disconnections (e.g., after extended periods), the cause may be:

1. Load balancer idle timeouts - AWS ALB has configurable timeouts (max ~66 minutes)
2. Proxy buffering - Nginx/CloudFront may buffer SSE responses
3. Network issues - Temporary disconnections

Troubleshooting Disconnections

If you experience frequent disconnections:

1. Check your network - Ensure stable internet connection
2. Try stdio mode locally - More reliable for local development
3. Check proxy settings - Ensure SSE buffering is disabled

Best Practice

For long-running sessions, consider using stdio mode locally or reconnecting periodically. The server maintains stateless operation, so reconnection is seamless.

Authentication & Workspace Setup

Prerequisites for Agent Management

To use agent management tools, you need:

1. API Key: Obtain from Admin > API Integration in your workspace
2. Workspace ID: Your unique workspace identifier which you can also find in the Admin section
3. Subscription: Business or Enterprise plan for external API access

API Access Requirements

External API access is available for Business and Enterprise subscriptions. Individual users can access AI features through the ToothFairyAI application and TF Code. See API Integration for details.

MCP Credential Setup

MCP vs CLI Tools

MCP tools and CLI tools use different credential systems:

• MCP Tools: Pass credentials directly to each tool call (no installation required)
• CLI Tools: Install separately and configure credentials in environment/config files

This documentation covers MCP tools only. For CLI tools, see API Integration.

For MCP operations, you need to provide credentials directly to each tool. The MCP server does not store or cache credentials - you must pass them with every authenticated operation.

Testing Credentials with MCP

Before creating agents, always validate your credentials using the MCP tool:

# Using the MCP tool - credentials passed directly
validate_toothfairy_credentials(
    api_key="your-api-key",
    workspace_id="your-workspace-id",
    region="au"
)

Credential Architecture & Security

The MCP server implements a secure, stateless credential system where credentials are never stored persistently. Each authenticated operation requires fresh credential parameters.

How Credentials Work

Dual Authentication System

The MCP server uses two authentication mechanisms:

1. HTTP Header Authentication

   headers = {
       "x-api-key": api_key,           # From Admin > API Integration
       "Content-Type": "application/json"
   }

2. Request Body Authentication

   payload = {
       "workspaceid": workspace_id,    # Your workspace UUID
       # ... other request data
   }

Required Workflow

Always follow this sequence for agent management:

# 1. Validate credentials first
validation_result = validate_toothfairy_credentials(
    api_key="your-api-key-from-admin",
    workspace_id="your-workspace-uuid",
    region="au"  # or "eu", "us"
)

# 2. Check validation success
if validation_result["success"]:
    # 3. Proceed with agent operations
    agent = create_toothfairy_agent(
        api_key="your-api-key-from-admin",
        workspace_id="your-workspace-uuid",
        region="au",
        label="Research Analyst",
        mode="retriever",
        # ... other agent configuration
    )
else:
    print(f"Authentication failed: {validation_result['error']}")

Security Features

• No Credential Storage: Credentials are never saved in the MCP server
• Fresh HTTP Client: New client created for each operation
• Context Manager: Ensures proper cleanup of connections
• Stateless Design: Each tool call requires explicit credentials

All Tools by Category

The MCP server provides 105 tools organized by category. SDK tools require api_key, workspace_id, and region parameters.

Category	Tools	Auth Required	Description
Documentation	10	❌ No	Search docs, API endpoints, get guides
Release Notes	4	❌ No	List, get, and search release notes
Public Utils	3	❌ No	Announcements, hireable agents, AI models
Credential Validation	1	✅ Yes	Validate credentials before operations
Agent Management	6	✅ Yes	Create, read, update, delete, list, search agents
Agent Functions	5	✅ Yes	External API tools for agents
Authorisations	5	✅ Yes	API key and OAuth credential storage
Secrets	2	✅ Yes	Encrypted secret management
Documents	6	✅ Yes	Knowledge base document management
Entities	6	✅ Yes	Topics, intents, and NER management
Folders	6	✅ Yes	Document folder organization
Chats	5	✅ Yes	Conversation sessions and messaging
Prompts	5	✅ Yes	Reusable prompt templates
Members	4	✅ Yes	Workspace user management
Channels	5	✅ Yes	Communication integrations (Slack, Teams, etc.)
Connections	3	✅ Yes	Database connections
Benchmarks	5	✅ Yes	Agent testing and evaluation
Hooks	5	✅ Yes	Custom code execution
Scheduled Jobs	5	✅ Yes	Automated recurring tasks
Sites	4	✅ Yes	Web deployments and widgets
Dictionary	2	✅ Yes	Custom terminology definitions
Request Logs	2	✅ Yes	API usage tracking
Settings	4	✅ Yes	Charting and embeddings configuration
Billing	1	✅ Yes	Monthly cost retrieval
Embeddings	1	✅ Yes	Text embedding generation

Complete Tool Reference

For detailed documentation of every tool including parameters, return types, and examples, see the Complete Tool Reference.

Credential Security

• Never hardcode credentials in your code
• Use environment variables or secure credential stores
• Always validate credentials before agent operations
• The MCP server does not cache or store your credentials

Common Authentication Errors

Error	Cause	Solution
401 Unauthorized	Invalid API key	Check API key in Admin > API Integration
403 Forbidden	Insufficient permissions	Upgrade to Business/Enterprise plan
404 Not Found	Invalid workspace ID	Verify workspace UUID
API access not allowed	Wrong subscription	Upgrade for API access

Documentation Resources

Documentation Access

The MCP server provides access to all ToothFairyAI documentation:

• Browse all documentation: toothfairy://docs/list
• Access specific document: toothfairy://docs/{category}/{slug}

Available Categories

Category	Description	Example Documents
Agents	Agent types, model choice, marketplace	Agent types, Model choice, Marketplace
Settings	Platform configuration and settings	Prompting, Functions, Channels, NER
Administrators	Workspace administration	User management, Dashboard, Embeddings
Knowledge Hub	Document and knowledge management	Documents, Images, Embedding status
Guides	Integration and usage guides	API integration, Twilio, Voice API

Search Capabilities

Full-text Documentation Search

search_docs(
    query="agent creation",
    limit=10,
    source="docs"  # Optional: "docs", "api", or None for all
)

Quick Topic Access

get_doc_by_topic("agents")

Documentation Search Flow

Release Notes Access

The MCP server provides tools to access ToothFairyAI release notes and product updates:

List All Release Notes

list_release_notes()

Returns all available release notes sorted by version (newest first).

Get Latest Release Notes

get_latest_release_notes()

Returns the full content of the most recent release.

Get Specific Version

get_release_notes(version="0.668.0")

Search Release Notes

search_release_notes(query="voice agents", limit=5)

Search across all release notes to find when specific features were introduced.

API Specifications & Domain Guidance

Critical: API Domain Distinction

ToothFairyAI has multiple API domains serving different purposes. Using the wrong domain will result in errors.

API Type	Base Domain	Purpose	Example Operations
Platform API	api.{region}.toothfairyai.com	Agent management & platform operations	Create/update/delete agents, functions, entities
AI Services API	ai.{region}.toothfairyai.com	AI operations & agent interaction	Chat with agents, planning, search, tokenization
Voice API	voice.{region}.toothfairyai.com	Voice-specific operations	Voice calls, speech-to-text, text-to-speech

AI Services Utilities

Additional endpoints are available on the streaming infrastructure (ais.* domains) for specialized operations. See the AI Services Utilities section below for details on the spawn-agent endpoint and other internal utilities.

API Discovery Tools

List All API Specifications

# Get comprehensive API spec list with domain info
toothfairy://api/list

Search for Specific Endpoints

search_api_endpoints(
    query="topic creation",
    limit=20
)

API Domain Decision Guide

Detailed Domain Explanation

For comprehensive guidance on API domain usage:

explain_api_domains()

AI Services Utilities

Dynamic Agent Generation

Some endpoints run on the streaming infrastructure (ais.* domains) and are used internally by ToothFairyAI systems.

Spawn Agent Endpoint

Endpoint: POST https://ais.{region}.toothfairyai.com/spawn-agent

The /spawn-agent endpoint is a utility primarily used internally by Orchestrator agents to dynamically generate task-specific agents during plan execution.

⚠️ Domain Note: This endpoint runs on the AI Services streaming domain (ais.{region}.toothfairyai.com), not the standard Platform API domain.

Purpose:

• Dynamically create temporary agents for specific tasks during orchestration
• Used by Orchestrator agents during multi-step plan execution
• Creates agents with specialized configurations for one-time use

When to Use:

• While accessible via API, this endpoint is designed for internal orchestration rather than standard agent management
• For creating permanent agents, use the Platform API endpoints (api.{region}.toothfairyai.com)

Key Differences from Platform API:

• Spawn Agent (ais.*): Creates temporary, task-specific agents during orchestration
• Platform API (api.*): Creates permanent agents for long-term use

Agent Creation & Management

Comprehensive Agent Creation Guide

Access the complete agent creation guide with all configuration details:

# Get full guide
get_agent_creation_guide()

# Get specific section
get_agent_creation_guide("modes")
get_agent_creation_guide("tools")
get_agent_creation_guide("examples")

Guide Sections Available

1. Agent Modes Overview - 6 modes with capabilities and restrictions
2. Core Fields Reference - 100+ fields with descriptions and defaults
3. Mode-Specific Configuration - Best practices for each mode
4. Tools System - Available tools by mode and customToolingInstructions
5. Feature Flags & Rules - Validation rules for feature combinations
6. Department Configuration - 12 departments with feature eligibility
7. Model Configuration - Model selection, temperature, token limits
8. Upload Permissions - Document, image, audio, video upload settings
9. Voice Agent Configuration - Voice-specific settings and restrictions
10. Orchestrator Configuration - Multi-agent coordination
11. Field Validation Rules - Required fields and conditional requirements
12. Best Practices - Naming, instructions, goals, latency considerations
13. Examples - Complete agent configurations for each mode

Tool Reference Syntax

In customToolingInstructions, always prefix tool IDs with @ symbol:

• ✅ Correct: "Use @rag to search documents. Use @internet_search for web research."
• ❌ Incorrect: "Use rag to search documents. Use internet_search for web research."

Agent Management Workflow

Step-by-Step Process

Create a New Agent

create_toothfairy_agent(
    api_key="your-api-key",
    workspace_id="your-workspace-id",
    label="Research Analyst",
    mode="retriever",
    interpolation_string="You are a Research Analyst with expertise in conducting comprehensive research across multiple domains...",
    goals="Conduct thorough research on any topic. Synthesize information from multiple sources. Provide well-structured reports with citations and data analysis.",
    description="A powerful research assistant that conducts comprehensive research using internet search, document analysis, and data processing.",
    agentic_rag=True,  # Enable multi-step autonomous RAG
    has_code=True,     # Enable code execution
    allow_internet_search=True,
    temperature=0.3,
    max_tokens=8192,
    department="RESEARCH_AND_DEVELOPMENT"
)

List Agents in Workspace

list_toothfairy_agents(
    api_key="your-api-key",
    workspace_id="your-workspace-id",
    region="au"
)

Update an Existing Agent

update_toothfairy_agent(
    api_key="your-api-key",
    workspace_id="your-workspace-id",
    agent_id="agent-uuid-here",
    updates={
        "label": "Updated Research Analyst",
        "temperature": 0.5,
        "allowInternetSearch": True
    }
)

Function (Tool) Management

Create external API tools for agents to use:

create_toothfairy_function(
    api_key="your-api-key",
    workspace_id="your-workspace-id",
    label="Weather API",
    description="Get current weather information for a location",
    authentication_type="apikey",
    url="https://api.weatherapi.com/v1/current.json",
    method="GET",
    parameters={
        "type": "object",
        "properties": {
            "q": {
                "type": "string",
                "description": "City name or ZIP code"
            }
        },
        "required": ["q"]
    },
    headers={
        "key": "${WEATHER_API_KEY}"
    }
)

MCP Prompts & Templates

Available Templates

Generate API Usage Guide

api_usage_guide(
    endpoint="/agent/create"
)

Create Feature Documentation

feature_guide(
    feature="agenticRAG"
)

Generate Agent Configuration

create_agent(
    agent_type="research",
    use_case="document analysis and research"
)

Integration Examples

Python Programmatic Access

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

async def use_toothfairy_mcp():
    async with sse_client(url="https://mcp.toothfairyai.com/sse") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # Search documentation
            docs = await session.call_tool("search_docs", {
                "query": "agent creation",
                "limit": 5
            })
            
            # Get API endpoints
            endpoints = await session.call_tool("search_api_endpoints", {
                "query": "chat",
                "limit": 10
            })
            
            # Get agent creation guide
            guide = await session.call_tool("get_agent_creation_guide", {
                "section": "examples"
            })

Common Use Cases

1. Research Assistant

• Documentation search for platform features
• API endpoint discovery and usage examples
• Agent configuration guidance

2. Agent Developer

• Access comprehensive agent creation guide
• Validate agent configurations
• Create and manage agents programmatically

3. API Integrator

• Discover available endpoints
• Understand API domain distinctions
• Generate usage examples and guides

4. Workflow Automation

• Automate agent creation and management
• Create external API tools for agents
• Monitor and update agent configurations

Best Practices

API Domain Usage

• Platform API (api.*): Use for managing agents (create, update, delete, list)
• AI Services API (ai.*): Use for interacting with agents (chat, search, tokenization)
• Voice API (voice.*): Use for voice-specific operations

Tool Reference Syntax

• Always use @ prefix in customToolingInstructions: @rag, @internet_search, @code_interpreter
• interpolationString should use natural language, not tool IDs

Agent Configuration

• Follow mode-specific recommendations from the agent creation guide
• Validate feature flag combinations (e.g., agenticRAG only with mode="retriever")
• Use appropriate departments based on agent purpose

Error Handling

• Always validate credentials before agent operations
• Check API access requirements for your subscription
• Monitor rate limits and intelligence budget usage

Deployment & Configuration

Transport Modes

HTTP Mode (SSE)

• Remote access for AI assistants and tools
• Real-time communication via Server-Sent Events
• Built-in 15-second pings for connection reliability
• Production use with https://mcp.toothfairyai.com/sse

stdio Mode

• Local use with Claude Code and development tools
• Direct process communication
• Development and testing
• More reliable for long-running sessions

Environment Variables

Variable	Description	Default
MCP_TRANSPORT	Transport type: "stdio" or "http"	"http"
MCP_HOST	HTTP server host	"0.0.0.0"
MCP_PORT	HTTP server port	8000
DOCS_PATH	Path to markdown documentation	"docs/tf_docs/docs"
API_DOCS_PATH	Path to API documentation	"docs/api_docs/public"

Health & Monitoring

Check server health and version programmatically:

# Health check
curl https://mcp.toothfairyai.com/health

# Server info (includes version, tool counts, etc.)
curl https://mcp.toothfairyai.com/info

Troubleshooting & Support

Common Issues

Authentication Errors

{
  "errorMessage": "API access not allowed for this subscription type"
}

Solution: Upgrade to Business or Enterprise for API access.

Endpoint Not Found

{
  "errorMessage": "No spec found for name='agents'"
}

Solution: Use correct spec names: "platform", "ai-services", "voice".

Incorrect API Domain

Symptom: API requests fail with domain-related errors Solution: Use explain_api_domains() tool to understand which API to use.

Connection Drops

Symptom: MCP connection disconnects after extended period Solution: The server sends 15-second pings automatically. If issues persist:

• Check your network stability
• Try stdio mode for local use
• Ensure no proxy is buffering SSE responses

Support Resources

• API Documentation: https://apidocs.toothfairyai.com
• Main Documentation: https://docs.toothfairyai.com
• Related Guides:
  • API Integration
  • Functions & Tools
  • Agent Management

Roadmap & Future Features

Regional Expansion

• US Endpoint: https://mcp.us.toothfairyai.com/sse 🚧 Coming Soon

A2A Protocol Support ✅ Available

• Agent-to-Agent communication protocol for multi-agent workflows
• JSON-RPC 2.0 standard for universal agent interoperability
• Task-based conversations with lifecycle tracking (active, completed, failed, canceled)
• Agent Cards for standardized capability discovery
• Streaming responses via Server-Sent Events (SSE)

📖 Documentation: A2A Protocol Integration 📖 API Specification: apidocs.toothfairyai.com (select "TF A2A" from the dropdown)

Enhanced SDK Integration ✅ Available

The MCP server provides 105 tools across 24 categories, powered by the ToothFairyAI Python SDK:

Core Management:

• Agent Management - Create, read, update, delete, list, and search agents
• Agent Functions - External API tools for agents
• Authorisations & Secrets - API key, OAuth, and credential storage

Knowledge Hub:

• Documents - Upload, retrieve, and manage knowledge base documents
• Folders - Organize documents into folder structures
• Entities - Topics, intents, and NER management

Communication:

• Chats - Conversation sessions and messaging with send_toothfairy_message
• Channels - Slack, Teams, and other integrations
• Sites - Web deployments and widgets

Configuration:

• Prompts - Reusable prompt templates
• Hooks - Custom code execution
• Connections - Database connections
• Dictionary - Custom terminology definitions

Operations:

• Members - Workspace user management
• Benchmarks - Agent testing and evaluation
• Scheduled Jobs - Automated recurring tasks
• Request Logs - API usage tracking
• Billing - Monthly cost retrieval
• Embeddings - Text embedding generation
• Settings - Charting and embeddings configuration

Documentation Access:

• Release Notes - list_release_notes, get_latest_release_notes, get_release_notes, search_release_notes
• Documentation Search - Search and retrieve platform documentation
• API Specifications - Access OpenAPI specs for all ToothFairyAI APIs

Install the SDK directly: pip install toothfairyai

Getting Help

For questions about MCP integration, agent creation, or API usage:

1. Check the comprehensive API documentation
2. Review the Complete Tool Reference for all 105 tools
3. Install the ToothFairyAI Python SDK for direct API access: pip install toothfairyai
4. Use get_agent_creation_guide() for agent configuration
5. Use explain_api_domains() for API domain guidance
6. Contact support for subscription and access questions