MCP Host & Agent Integration Guide

toorow operates as a FastMCP microkernel server (server/core/main.py), exposing audited data tools and interactive MCP App UI widgets to artificial intelligence agents.

1. The Two Agent Paradigms in Toorow

toorow orchestrates two distinct agent paradigms that operate in tandem across the platform:

+-------------------------------------------------------------------------------+
|                               TOOROW PLATFORM                                 |
|                                                                               |
|  +---------------------------------+   +-----------------------------------+  |
|  |  1. INTERNAL PLATFORM AGENTS    |   |  2. EXTERNAL LLM HOST AGENTS      |  |
|  |  (In-Process Scheduled Threads) |   |  (Claude Desktop, Cursor, LLMs)   |  |
|  |                                 |   |                                   |  |
|  |  - Nightly Ingestion Evaluator  |   |  - FastMCP Streamable HTTP        |  |
|  |  - Anomaly Surveillance Thread  |   |    endpoint (port 8000 / 8080)    |  |
|  |  - Daily Insight Composer      |   |  - Dual-Channel Response (Text +   |  |
|  |  - Quality & Provenance Auditor |   |    structuredContent UI Widgets)  |  |
|  +---------------------------------+   +-----------------------------------+  |
|                                  \       /                                    |
|                                   v     v                                     |
|                       +------------------------+                              |
|                       |   FASTMCP MICROKERNEL  |                              |
|                       +------------------------+                              |
+-------------------------------------------------------------------------------+

Paradigm 1: Internal / Platform Agents (Scheduled)

toorow runs work when nobody is watching. In a managed deployment the clock is Cloud Scheduler, units of work are Cloud Tasks, and facts are broadcast on Pub/Sub; a self-hosted instance can instead run the same evaluators as in-process threads with SCHEDULER_ENABLED=true. Either way the same three evaluators run:

Ingestion & dbt Evaluator: Fetches active connector datastreams and runs dbt semantic models. Each Datastream carries its own moment — cadence, retrieval window and next run are edited on the Datastream itself, not fixed platform-wide. A Datastream that has never been given one falls back to the deployment default (SCHEDULER_NIGHTLY_HOUR, SCHEDULER_TIMEZONE).
Anomaly Surveillance Thread: Evaluates trailing rolling baselines (anomalies_daily) to detect performance spikes or drops exceeding z-score thresholds.
Daily Insight Composer: Assembles KPI deltas, the anomalies that fired, and the active context events into a daily insight.

Paradigm 2: External LLM Host Agents (FastMCP HTTP Clients)

External agents are conversational or autonomous LLM clients (such as Claude Desktop, Cursor, Google Antigravity, or custom Python/TypeScript AI agents) that connect to toorow’s FastMCP server over HTTP:

Transport Endpoint: http://localhost:8000/mcp (local dev), or /mcp on the host that serves the toorow server itself in production.

If you front the server with a static host, /mcp must be rewritten to it. Only the paths a static host is told to forward reach the server; everything else falls through to the console’s own page. Measured 2026-09-06 on the maintainers’ deployment, before the rule was applied: /mcp answered 200 text/html — the console — so an MCP host pointed at it received HTML where it expects JSON-RPC, and the failure looked like a broken server rather than a routing rule. The paths that must cross are /api/**, /mcp, /mcp/**, /share, /share/** and /handoff.

Dual-Channel Protocol: External hosts receive a short LLM text summary for prompt insertion while rendering embedded MCP App UI widgets (ui/widgets/) directly inside client chat interfaces.

2. Configuring External MCP Host Clients

Claude Desktop Configuration

Add toorow as an HTTP MCP server in your claude_desktop_config.json:

{
  "mcpServers": {
    "toorow": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-fetch",
        "http://localhost:8000/mcp"
      ]
    }
  }
}

For production Cloud Run endpoints secured with OAuth (TOOROW_AUTH_MODE=oauth), pass the bearer token header:

{
  "mcpServers": {
    "toorow-prod": {
      "url": "https://<your-toorow-server>/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_JWT_BEARER_TOKEN>"
      }
    }
  }
}

Cursor IDE Configuration

To configure toorow in Cursor:

Open Cursor Settings -> Features -> MCP Servers.
Click + Add New MCP Server.
Set Name to toorow.
Set Type to sse or command.
Enter endpoint URL: http://localhost:8000/mcp.

Google Antigravity Configuration

In Google Antigravity, toorow can be registered directly as an eager or lazy MCP tool in your configuration profile (~/.gemini/antigravity/mcp/toorow.json):

{
  "name": "toorow",
  "transport": "http",
  "url": "http://localhost:8000/mcp"
}

3. FastMCP Streamable HTTP Transport Protocol

toorow implements the FastMCP HTTP transport protocol:

Endpoint: /mcp
Supported Methods: POST (JSON-RPC 2.0 tool execution) and GET (SSE stream for real-time tool status).
Host Header Enforcement: Production containers enforce strict host validation (HOST_HEADER_VALIDATION=strict, ALLOWED_HOST).

4. Agent Onboarding in 10 Minutes: Read the Context Hub, Write a Product Sheet

This is the shortest path for an external agent (CLI or custom) that must read toorow’s governed context — Skills, Knowledge, business taxonomy — and publish back into it, e.g. a product sheet following the Skill Write a toorow product sheet.

Connect

Any MCP client that speaks streamable HTTP works. A generic CLI config:

{
  "mcpServers": {
    "toorow": {
      "url": "http://localhost:8000/mcp",
      "headers": { "Authorization": "Bearer <TOOROW_STATIC_TOKEN>" }
    }
  }
}

TOOROW_AUTH_MODE=disabled (local default): omit the header entirely.
TOOROW_AUTH_MODE=static: the header is exactly Bearer <TOOROW_STATIC_TOKEN>.
TOOROW_AUTH_MODE=oauth: the header carries a JWT (RS256, audience/issuer enforced).

Scope: the `project_id` is real, not optional

search_context and get_procedure default project_id to "default", which matches nothing useful on a real instance. Ask the platform for the project id (GET /api/projects with the same bearer, or the console URL /org/<org>/project/<proj_...>/context-hub/... — the id is the proj_… slug in the path). Under oauth, the identity must hold a project grant or every context read refuses.

Read efficiently — the canonical sequence

search_context(query, project_id) — bounded LLM summary (≤ 30 lines) plus ranked hits in structuredContent (title/description/graph-neighbor tiers, 160-char snippets).
get_procedure(name, project_id) — the full Skill: parsed steps[], body_md, mdm_references, version. Same dual-channel shape.
get_knowledge(topic_id=…, project_id) — the full Knowledge body.

Where the payload actually lives. Any payload larger than 4 KiB is moved out of the model channel (Story 50.6): structuredContent.data.<key> then carries a descriptor {"withheld": "moved_to_app_channel", "bytes": N} and the full object is in _meta["toorow.app_payload"]. A client that only reads the text summary — or only structuredContent — never sees a Skill’s steps. Read _meta["toorow.app_payload"] whenever a withheld descriptor appears. Write tools answer with the id. add_knowledge / add_skill return the created object’s id, title/name and version_number in structuredContent.data — no need to parse the acknowledgement sentence. Avoid for discovery: get_skills, get_knowledge without a filter and get_context_hub return raw unbounded JSON, not the standard envelope with its meta/data split and its provenance. They are for when you already know what you want — reaching for them first is how an agent fills its context window with the whole Hub.

Publish a product sheet

Read the governing Skill first: search_context("product sheet") then get_procedure("Write a toorow product sheet") — its steps[] and acceptance are the contract (seven mandatory sections, governed metrics named by their field names, honest limits).
Write the sheet: add_knowledge(project_id, title, body_md, owner?).
Link it to its surface’s business key so the taxonomy walks to it: POST /api/context/business-links with relation_type: "explains" (REST — there is no MCP link tool yet).

Next Steps & Cross-References

Agent Tools Reference

The three profiles that gate the surface, and the tools you reach first.

MCP App Use Cases

Discover how agents trigger interactive MCP App UI widgets.

Agent Rules & Guidelines

Review system instructions and invariants for LLM prompts.

Agent Context & Metadata

Explore schema discovery and context event annotations.

Product Overview

Core Features & Analytics

AI Agents & MCP Protocol

API Reference

MCP Host & Agent Integration Guide

1. The Two Agent Paradigms in Toorow

Paradigm 1: Internal / Platform Agents (Scheduled)

Paradigm 2: External LLM Host Agents (FastMCP HTTP Clients)

2. Configuring External MCP Host Clients

Claude Desktop Configuration

Cursor IDE Configuration

Google Antigravity Configuration

3. FastMCP Streamable HTTP Transport Protocol

4. Agent Onboarding in 10 Minutes: Read the Context Hub, Write a Product Sheet

Connect

Scope: the `project_id` is real, not optional

Read efficiently — the canonical sequence

Publish a product sheet

Next Steps & Cross-References

Agent Tools Reference

MCP App Use Cases

Agent Rules & Guidelines

Agent Context & Metadata

​1. The Two Agent Paradigms in Toorow

​Paradigm 1: Internal / Platform Agents (Scheduled)

​Paradigm 2: External LLM Host Agents (FastMCP HTTP Clients)

​2. Configuring External MCP Host Clients

​Claude Desktop Configuration

​Cursor IDE Configuration

​Google Antigravity Configuration

​3. FastMCP Streamable HTTP Transport Protocol

​4. Agent Onboarding in 10 Minutes: Read the Context Hub, Write a Product Sheet

​Connect

​Scope: the project_id is real, not optional

​Read efficiently — the canonical sequence

​Publish a product sheet

​Next Steps & Cross-References

Agent Tools Reference

MCP App Use Cases

Agent Rules & Guidelines

Agent Context & Metadata

1. The Two Agent Paradigms in Toorow

Paradigm 1: Internal / Platform Agents (Scheduled)

Paradigm 2: External LLM Host Agents (FastMCP HTTP Clients)

2. Configuring External MCP Host Clients

Claude Desktop Configuration

Cursor IDE Configuration

Google Antigravity Configuration

3. FastMCP Streamable HTTP Transport Protocol

4. Agent Onboarding in 10 Minutes: Read the Context Hub, Write a Product Sheet

Connect

Scope: the `project_id` is real, not optional

Read efficiently — the canonical sequence

Publish a product sheet

Next Steps & Cross-References