Skip to main content

​
MCP Tools

Supersonic exposes 91 MCP tools across 17 categories. Every action — from the web UI, AI agent, Telegram bot, or external MCP client — is executed through the same mcp_execute() pipeline.

​
How It Works

result = mcp_execute(
    workspace=workspace,       # Workspace instance
    principal=principal,       # User or system principal
    tool_name="records.create",# Tool identifier
    params={"object_type": "company", "data": {"name": "Acme"}},
    channel="agent",           # "api" | "agent" | "telegram" | "mcp" | "system"
)
# Returns ToolResult(success=True, data={...})
Pipeline steps:
  1. Registry lookup (find the @mcp_tool function)
  2. Permission check (role-based: owner > admin > member)
  3. Execute (mutations wrapped in transaction.atomic())
  4. Audit log (always, on success and failure)
  5. State change notification (WebSocket + Telegram on mutation commit)

​
Tool Categories (91 total)

CategoryCountAgent AccessDescription
objects74ObjectType CRUD + field management
records88Record CRUD + search + relations
lists117Lists/pipelines + entries
views64Saved views CRUD + data
analytics44Aggregations, pipeline, datalake
tasks66Task management
integrations100Connector management
timeline22Activity timeline
customer36022Customer health + summary
email54Email management + send
messages43Messaging (WhatsApp, Slack)
meetings53Meeting management + transcripts
calendar30Calendar events
billing50Invoices, subscriptions, payments
support50Support tickets
enrichment40Company/person enrichment
documents40Document management
telegram66Telegram bot management
Agent Access = tools whitelisted in agent/tool_schemas.py (47 total).

​
Tool Registration

Tools are registered with the @mcp_tool decorator: 
@mcp_tool(
    name="records.create",
    description="Create a new record",
    required_role=Member.Role.MEMBER,  # minimum role required
    is_read_only=False,                # if True, no audit log for reads
    category="records",
)
def records_create(ctx: ToolContext):
    # ctx.workspace — current workspace
    # ctx.principal — user/system principal
    # ctx.params — input parameters (validated)
    record = Record.objects.create(...)
    return ToolResult(success=True, data={...})

​
For External AI Agents (MCP Protocol)

Supersonic exposes tools via the MCP SDK (mcp==1.2.0). External AI agents can discover and call tools using the standard MCP protocol: 
from mcp import get_mcp_tool_definitions

# Returns tool definitions in MCP format
tools = get_mcp_tool_definitions(workspace_id)
Each tool definition includes:
  • name — tool identifier (e.g. records.create)
  • description — what the tool does
  • input_schema — JSON Schema for parameters