MCP Servers

TF Code supports MCP (Model Context Protocol) servers for integrating external tools and services. The ToothFairyAI MCP server is auto-configured from your profile credentials and available exclusively through the TF Engineer agent.

ToothFairyAI MCP Server

The primary MCP server provides 100+ tools for workspace operations. TF Engineer connects automatically via SSE based on your configured region:

Region	SSE Endpoint
AU	`https://mcp.toothfairyai.com/sse`
EU	`https://mcp.eu.toothfairyai.com/sse`
US	`https://mcp.us.toothfairyai.com/sse`
Dev	`https://mcp.toothfairylab.link/sse`

Credential Injection

When TF Engineer calls an MCP tool, credentials are handled transparently:

Your profile credentials (api_key, workspace_id, region) are loaded
They are injected as an x-api-key header and auto-filled parameters on the MCP server
The tool schema presented to the model has these fields stripped — the model never sees your credentials
Each tool invocation creates a fresh authenticated client on the server side

No authorisation secrets are stored locally. For tools where auth_via = "user_provided", you can store a per-tool API key locally via tfcode tools credentials <name> --set. All other authentication (OAuth, bearer tokens, etc.) is handled server-side by the ToothFairyAI backend.

Local MCP Servers

Add local MCP servers via stdio transport in your config:

{
  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_value"
      }
    }
  }
}

Option	Type	Required	Description
`type`	String	Yes	Must be `"local"`
`command`	Array	Yes	Command and arguments to run the MCP server
`cwd`	String	No	Working directory for the server process
`environment`	Object	No	Environment variables for the server
`enabled`	Bool	No	Enable or disable on startup
`timeout`	Number	No	Timeout in ms for fetching tools (default 5000)

CLI:

tfcode mcp list
tfcode mcp add /path/to/server --name my-server

Remote MCP Servers

{
  "mcp": {
    "my-remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

OAuth-Enabled MCP Servers

tfcode mcp auth https://mcp.example.com

TF Code automatically handles OAuth — detects 401 responses, initiates the flow, uses Dynamic Client Registration (RFC 7591), and stores tokens securely.

Pre-registered client credentials:

{
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

Disable OAuth auto-detection:

{
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

Sync

When TF Code starts (with sync.on_startup: true), it fetches metadata from your workspace:

What's Synced	How It's Used
Coder Agents	Become selectable agents with their own prompts and config
Agent Skills	Appear in the `skill` tool's available skills list
Prompt Templates	Injected into Coder Agent system prompts
API Functions	Cached as metadata; invoked through MCP server when needed

What Sync Does NOT Fetch

MCP servers — Must be manually configured in tfcode.json under mcp
Authorisation secrets — OAuth tokens, bearer tokens, API keys, passwords are never stored locally. Only auth_via metadata is cached.
Execution code — Skill scripts, database scripts, and custom execution code are not synced
Database scripts — Not currently classified by sync
Non-coder agents — Only agents with mode='coder' are synced

Sync Cache

~/.local/share/tfcode/.tfcode/tools.json           # Default profile
~/.local/share/tfcode/.tfcode/tools-{profile}.json  # Named profiles

Manual Sync

tfcode sync
tfcode sync --profile prod

Sync Config

{
  "toothfairy": {
    "sync": {
      "on_startup": true,
      "interval": 3600,
      "tools": {
        "types": ["mcp", "skill", "database", "function"]
      }
    }
  }
}

The types list includes "mcp" and "database" for future compatibility, but these are not currently synced.

Skills

Skills are step-by-step guided workflows served by the ToothFairyAI MCP server. They include validation rules, character limits, multi-step flows, example payloads, and error recovery patterns.

Skill	Description
`create-agent`	Create agents with mode-specific validation (coder requires `has_code=True`)
`setup-authorisation`	Set up API credentials for external integrations (OAuth, bearer, apikey, basic)
`create-function`	Create agent functions/tools with JSON Schema validation
`create-scheduled-job`	Create scheduled jobs with cron validation
`create-document`	Create and upload documents to the knowledge base
`create-connection`	Create AI model connections
`create-member`	Add workspace members
`update-prompt`	Update prompt templates
`document-workflow`	Multi-step document creation with folder management
`agent-interaction`	Interact with agents via the chat API

Skills are automatically invoked by TF Engineer when needed. The MCP server provides a recommend_skill_for_operation tool that maps natural-language descriptions to the right skill.

tfcode run --agent "TF Engineer" "Create a new coder agent called PythonExpert"
tfcode run --agent "TF Engineer" "I need to set up OAuth — which skill should I use?"

Functions (Tools)

Functions are agent functions for external API calls, managed through TF Engineer via the MCP server.

Authentication

`auth_via`	How it works
`tf_proxy`	ToothFairyAI backend proxy handles auth — no local credentials needed
`user_provided`	You store a per-tool API key locally via `tfcode tools credentials <name> --set`
`tf_skill`	Handled as part of the skill execution on the backend
`tf_agent`	Handled as part of the agent execution on the backend

Secrets are never stored locally. Only user_provided stores anything locally (a single API key per tool).

tfcode run --agent "TF Engineer" "Create a function called 'get_weather' that calls https://api.weather.com/current"

MCP Resources

The MCP server also exposes addressable resources:

Resource URI	Content
`toothfairy://docs/list`	List all documentation pages
`toothfairy://docs/{category}/{slug}`	Get specific documentation page
`toothfairy://api/list`	List all API specs
`toothfairy://api/{name}`	Get OpenAPI spec
`toothfairy://api/{name}/endpoints`	Get endpoint summary
`toothfairy://api/integration-guide`	Voice API integration guide

MCP Prompts

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

Tool Permissions

Control MCP tools via permissions. Disable globally, enable per-agent:

{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

Glob patterns: * matches zero or more characters, ? matches one character. MCP server tools are registered with the server name as prefix, so "myserver_*": false disables all tools for that server.

ToothFairyAI MCP Server​

Credential Injection​

Local MCP Servers​

Remote MCP Servers​

OAuth-Enabled MCP Servers​

Sync​

What Sync Does NOT Fetch​

Sync Cache​

Manual Sync​

Sync Config​

Skills​

Functions (Tools)​

Authentication​

MCP Resources​

MCP Prompts​

Tool Permissions​