MCP Integration

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, and agent management capabilities.

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	🚧 Coming Soon
Production	US	https://mcp.us.toothfairyai.com/sse	🚧 Coming Soon

Client Configuration

Claude Desktop Configuration

Add the MCP server to your Claude Desktop configuration:

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

Claude Code Command Line

Use the Claude Code CLI to add the MCP server:

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

Architecture Overview

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. Starter and Pro users can access AI features through the ToothFairyAI application. 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 Requiring Credentials

Tool	Required Parameters	Purpose
validate_toothfairy_credentials()	api_key, workspace_id, region	Validate before operations
create_toothfairy_agent()	api_key, workspace_id, region + config	Create new agent
list_toothfairy_agents()	api_key, workspace_id, region	List workspace agents
get_toothfairy_agent()	api_key, workspace_id, region, agent_id	Get agent details
update_toothfairy_agent()	api_key, workspace_id, region, agent_id, updates	Update agent
delete_toothfairy_agent()	api_key, workspace_id, region, agent_id	Delete agent
create_toothfairy_function()	api_key, workspace_id, region + config	Create external API tool
list_toothfairy_functions()	api_key, workspace_id, region	List functions
get_toothfairy_function()	api_key, workspace_id, region, function_id	Get function details
update_toothfairy_function()	api_key, workspace_id, region, function_id, updates	Update function
delete_toothfairy_function()	api_key, workspace_id, region, function_id	Delete function
list_toothfairy_prompts()	api_key, workspace_id, region	List prompt templates
get_toothfairy_prompt()	api_key, workspace_id, region, prompt_id	Get prompt details

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

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

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()

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 - 5 modes with capabilities and restrictions
2. Core Fields Reference - 50+ 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 - 15 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
• Production use with https://mcp.toothfairyai.com/sse

stdio Mode

• Local use with Claude Code and development tools
• Direct process communication
• Development and testing

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

• Health Check: https://mcp.toothfairyai.com/health
• Server Info: 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.

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

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

A2A Protocol Support 🚧 Coming Soon

• Agent-to-Agent communication protocol
• Enhanced interoperability between AI agents
• Standardized agent discovery and collaboration

Enhanced SDK Integration

• Additional tools for chat, documents, and entities
• Expanded agent management capabilities
• Improved documentation and search features

Getting Help

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

1. Check the comprehensive API documentation
2. Review the agent creation guide via get_agent_creation_guide()
3. Use explain_api_domains() for API usage guidance
4. Contact support for subscription and access questions