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}"
      }
    }
  }
}

MCP Apps (Interactive UI)

TF Code is compatible with the MCP Apps extension. An MCP App is an interactive HTML interface (chart, form, dashboard, viewer) returned by an MCP tool: instead of rendering plain text, TF Code displays the app inline in the conversation inside a sandboxed iframe.

How It Works

The MCP tool declares a UI resource in its _meta.ui metadata
When the model calls the tool, TF Code shows a text summary of the result and renders the app inline
The app receives the full tool result over a JSON-RPC postMessage channel (ui/notifications/tool-result)
The app can call other tools on the same MCP server through the tools/call proxy — each call shows a consent prompt and is gated by the same tool.use policy as model-invoked calls

Where Apps Render

Surface	Rendering
Web app	Sandboxed iframe, inline in the message timeline
Desktop	Same as web app (shares the renderer)
TUI / terminal	Not supported — text result summary is shown instead

Writing a Compatible Tool

Declare _meta.ui on the tool definition (standard and legacy ui/resourceUri metadata formats are both supported):

{
  "name": "show_chart",
  "description": "Show an interactive sales chart",
  "_meta": {
    "ui": {
      "resourceUri": "ui://my-app/chart.html",
      "visibility": ["model", "app"],
      "csp": {
        "connectDomains": [],
        "resourceDomains": ["https://cdn.example.com"]
      }
    }
  }
}

Expose the referenced resource with an MCP App MIME type:

{
  "uri": "ui://my-app/chart.html",
  "mimeType": "text/html;profile=mcp-app",
  "text": "<!doctype html> …"
}

The HTML must implement the MCP Apps postMessage protocol (send ui/initialize, then ui/notifications/initialized, listen for tool notifications). See the MCP Apps docs and the @modelcontextprotocol/ext-apps package for the app-side client.

UI Metadata Fields

Field	Required	Description
`resourceUri`	Yes	`ui://` URI of the HTML resource
`visibility`	No	`["model", "app"]` (default) — `["model"]` renders no UI; `["app"]` hides the tool from the model
`csp.connectDomains`	No	Origins the app may connect to via `fetch`/WebSocket
`csp.resourceDomains`	No	External origins the app may load scripts, styles, images, and fonts from
`csp.frameDomains`	No	Origins the app may embed in nested iframes
`permissions`	No	Camera/microphone/geolocation requests — not granted by TF Code v1

Security Model

Apps are rendered in a sandboxed iframe (allow-scripts, no same-origin) — they cannot access the host page, cookies, or storage
TF Code enforces a CSP: external resources are blocked unless the server declares them in _meta.ui.csp
App-initiated tool calls require user consent on first use and pass through the same permission policy as model calls

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

Tool results may also include resource_link content items — TF Code surfaces them as text links (name and URI) in the model context instead of dropping them.

MCP Apps Resources

Resources with the ui:// scheme and an MCP App MIME type (text/html;profile=mcp-app) are treated as MCP Apps UI resources — see the MCP Apps section above.

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​

MCP Apps (Interactive UI)​

How It Works​

Where Apps Render​

Writing a Compatible Tool​

UI Metadata Fields​

Security Model​

Sync​

What Sync Does NOT Fetch​

Sync Cache​

Manual Sync​

Sync Config​

Skills​

Functions (Tools)​

Authentication​

MCP Resources​

MCP Apps Resources​

MCP Prompts​

Tool Permissions​