TrailGuide

For developers

Build on the orchestration layer.

TrailGuide exposes its whole control plane over MCP — one remote server, one OAuth connection, ~60 tools. Connect Claude (or any MCP client) and drive audiences, campaigns, personalization endpoints, journeys, and governance programmatically — plus an autonomous agent fleet, community boosts, and read-only analysis over your own warehouse, event stream, and Mixpanel. This is the reference.

Connect

The MCP endpoint is a remote Streamable-HTTP server at:

https://trailguide.co/api/personalizer/mcp

Auth is OAuth 2.1 (one-click, DCR + PKCE). Pick your client:

Claude Code (CLI)

claude mcp add --transport http --scope user trailguide https://trailguide.co/api/personalizer/mcp

Then start an interactive session (claude), run /mcp, select trailguide, and log in when the browser opens. Confirm with /mcp again, then try “give me the Decisioner overview.”

Claude Desktop / web

Settings → Connectors → Add custom connector → paste the endpoint → Connect and approve in the browser. Fully quit and reopen Desktop if it doesn’t appear. On web, use the OAuth flow — pasted header tokens are unreliable there.

Headless (claude -p, the SDK, CI)

A non-interactive session can’t run the browser OAuth step, so use a static token instead: grab one from the Connect page (or orchestration_mcp_token) and send it as an Authorization: Bearer (or x-orchestration-mcp-token) header. Tokens are org-scoped secrets — keep them server-side, never in chat.

The model

  • Org-scoped. Every tool takes an organizationId (your TrailGuide org UUID). One connection can operate any org your token is authorized for; the connected user is attributed on every call.
  • Layered, not a silo. TrailGuide sits on top of your warehouse (BigQuery), your push (OneSignal) and email, and your analytics (RudderStack). It reads and writes through those; it doesn’t replace them.
  • Bring your own schema. Point the layer at your warehouse (BigQuery, PostgreSQL, or Supabase), have it introspect your tables and columns, and map them to the model it reasons over: an identity column, a profile table, an event table, and named roles (paid status, member lifecycle, saves, mobile events, feed comments, subscribe events). Everything downstream then speaks your data, not ours, and a filter type stays available only once the role it needs is mapped. orchestration_data_sources (discover_schema, get_semantic_model, set_semantic_model).
  • Bring your own model. Connect your own LLM and every AI feature in TrailGuide runs on it — the teammate fleet, the assistant, all campaign and email copy, and the in-app AI tools. Supported: Anthropic (direct, or Claude on your own Amazon Bedrock / Google Vertex account so inference stays in your AWS / GCP), OpenAI, Google Gemini, Azure OpenAI, Mistral, OpenRouter, or any OpenAI-compatible endpoint. Prompts and generated content then go to your provider under your own data-retention terms; TrailGuide never routes your content to its own model provider. Connect, switch, and test it under Bots & Models or via orchestration_model; the key is stored encrypted at rest and never returned. With nothing connected, everything runs on the TrailGuide platform default (byte-for-byte the prior behavior). An owner/admin can also set an org-wide zero-retention preference to minimize platform-side retention of prompts and output.
  • Read freely, write deliberately. Reads, previews, estimates, and dry runs are always safe. Anything that sends or goes live is gated (see Safety).

Concepts

Data source & data model

A warehouse connection (BigQuery) and a Zero-Copy mapping of its fields into the customer catalog the layer reasons over. Tools: orchestration_data_sources, orchestration_data_models, orchestration_customer_catalog.

Segment

A reusable audience defined by filters over your mapped model (built from a natural-language prompt), kept fresh on a schedule. Combine filters with match ALL (AND) or match ANY (OR), subtract with NOT (“active users except paid subscribers”), and compare any modeled warehouse column (equals, contains, numeric or date ranges, in-list) with a warehouse_predicate. A filter that can’t be evaluated for your data fails closed (nobody), never the whole org. orchestration_segments, orchestration_audience_estimate, orchestration_campaign_schema.

Endpoint

A live personalization API (/api/personalizer/v1/{slug}) that returns per-user recommendations for your app or site. orchestration_endpoints, orchestration_recipes.

Webhook (campaign)

One outbound send config: a channel (push, email, SMS, Slack, or a generic HTTP endpoint), an audience, a message template, a schedule, and analytics/targeting. HTTP campaigns POST a system-rendered body by default, or a custom JSON shape you define with a bodyTemplate (map the fields to what your endpoint expects). SMS/Slack read their credentials from a connected integration. Installs paused. orchestration_webhooks, orchestration_webhook_config, orchestration_webhook_send.

Sequence (journey)

A multi-step flow linked to a webhook, with re-eligibility and goal config. Triggers can start it from a warehouse signal. orchestration_sequences, orchestration_triggers.

Governance

A global holdout for lift measurement, org-wide frequency caps, a kill switch, and per-campaign expectations that fire alerts on drift. orchestration_global_holdout, orchestration_frequency_caps, orchestration_kill_switch.

The agent fleet

Bounded, reversible-internal coworkers that live on the Workflow chat: a Proposer/Critic debate (Blaze & Ranger), an opportunity scout (Pathfinder), a codebase scout (Cairn), and a PR reviewer (Summit) — plus a factory for your own custom persona bots. They only post notes and file draft tasks; they never send. orchestration_agent_loop, orchestration_pathfinder, orchestration_bots.

Master Blaster

Community boosts that spotlight a great member post to your active audience — with all-time never-boost-the-same-member-twice de-dup, a compliance gate, and an N-way split mode. Dry by default. orchestration_master_blaster_candidates, orchestration_master_blaster_split.

Analytics (bring your own)

Read-only, cost-bounded analysis over your own data: fixed activation/engagement funnels (App Intelligence), ad-hoc queries against your BigQuery warehouse, your inbound event stream, and your connected Mixpanel project. orchestration_app_intel, orchestration_query, orchestration_events, orchestration_mixpanel.

Agents & automation

Beyond the tools you call directly, TrailGuide ships a fleet of bounded, reversible-internal agents that work the backlog with you. Each pulls a few cheap, capped signals, asks a small model to synthesize a couple of concrete, grounded findings, and posts them to the Workflow chat as a named coworker plus a draft task. None of them can send a message, fire a campaign, change a setting, or write to GitHub — they only post internal notes and file drafts.

Blaze & Ranger — propose & critique

orchestration_agent_loop runs a capped Proposer/Critic debate on a topic: Blaze opens with a concrete point, Ranger stress-tests it, and it closes with a recommendation filed as a draft task.

Pathfinder — opportunity scout

orchestration_pathfinder reads the App Intelligence funnels and Master Blaster candidates to surface the 2–3 highest-value growth opportunities, each tied to a specific number and a reversible next step.

Cairn — codebase scout

orchestration_cairn maps the biggest telemetry drop-offs to the source that backs them (when you connect your GitHub repo), tying a metric to a specific screen and file.

Summit — PR reviewer

orchestration_summit reviews one open pull request (read-only on GitHub) and files 2–3 correctness / risk / test-gap findings as coworker notes.

Custom bots

orchestration_bots is a factory for your own persona coworkers — a name, a role, a system prompt, and one of ~50 animated faces. People @tag or DM them in the team chat and they reply in character. A bot is a conversational persona only; it grants no outward capability.

The fleet is gated behind org flags (agentLoopEnabled, agentsEnabled) and inert until switched on. Add dryRun to the scouts to synthesize findings without posting anything.

Tool reference

~60 tools, grouped by job. Each takes organizationId plus its own params; most use an action field (list / get / create / update). Ask orchestration_campaign_schema for exact shapes. Reads, previews, estimates, and the analysis tools are always safe; anything that sends is gated.

Overview & data

orchestration_get_overviewDashboard snapshot: webhooks, sequences, segments, integrations, kill switch.
orchestration_data_sourcesConnect / list warehouse sources; discover schema (BigQuery, PostgreSQL, Supabase); read + author the semantic model that maps your tables to the roles segments use.
orchestration_data_modelsZero-Copy data models + warehouse field mappings.
orchestration_customer_catalogRead the warehouse field catalog; save agentic context overrides.

Audiences

orchestration_segmentsList / get / create / update / refresh audience segments from NL filters.
orchestration_audience_estimateSize an audience before you build or send.

Personalization

orchestration_endpointsCreate / update live personalization API endpoints.
orchestration_recipesRecipe personalization config + preview.

Campaigns & sends

orchestration_webhooksList / get / create / update campaigns; set expectations.
orchestration_webhook_configDeeper message + targeting config for one campaign.
orchestration_webhook_sendPreview, dry-run, test-send, or fire a campaign (full send-safety stack). HTTP preview renders the exact request (with your bodyTemplate applied) and sends nothing.
orchestration_webhook_killImmediately stop sends for one campaign.
orchestration_campaign_templatesPrebuilt campaign shapes to install.
orchestration_campaign_schemaThe exact JSON shapes for filters, templates, and configs.
orchestration_dry_runSize + render a real run without sending anything.

Journeys

orchestration_sequencesList / get / create / update multi-step sequences (incl. build_simple).
orchestration_sequence_killStop a sequence by pausing its webhook.
orchestration_triggersRead / control signup-trigger polling; trigger activity feed.
orchestration_install_presetInstall a ready-made flow (welcome, win-back, trending, etc.).
orchestration_pipelineRefresh segment membership + fire the webhook pipeline.

Copy

orchestration_copy_generateAI-write push/email copy in the brand voice.
orchestration_copy_voiceRead / set the org brand voice.
orchestration_email_templatesManage email templates + fixtures.

Safety & governance

orchestration_global_holdoutRead / set the org-wide holdout percent.
orchestration_frequency_capsRead / update org-wide message frequency caps.
orchestration_kill_switchOrg-wide emergency stop / resume for all sends.
orchestration_logsOutbound delivery logs, org-wide or per campaign.
orchestration_reportsPerformance reports: delivery, opens, clicks, lift vs holdout.
orchestration_usage/ billing — usage metering and cost.

Integrations & access

orchestration_integrationsList / upsert / test connectors: OneSignal, RudderStack, GitHub, Mixpanel, event stream, and AI models.
orchestration_modelBring-your-own-model: list connected models, pick the active one, test a round-trip.
orchestration_repoRead-only reads over your connected GitHub repo (tree / file / search / commits / pulls / branches).
orchestration_mcp_tokenIssue / inspect the org’s MCP token (for headless).
orchestration_onboard_clientOperator-only: stand up a new client org from a spec.

Analytics & data

orchestration_app_intelApp Intelligence: fixed activation / engagement / cook funnels with drop-offs (read-only, cost-bounded).
orchestration_queryBounded read-only query over your BigQuery warehouse — structured spec or constrained SQL.
orchestration_eventsYour inbound event stream: ingestion info + filter / aggregate / funnel / retention over received events.
orchestration_mixpanelRead-only analysis over your connected Mixpanel: segmentation, funnels, retention, cohorts, JQL.

Agents & the fleet

orchestration_agent_loopBounded Proposer/Critic debate (Blaze & Ranger) on a topic; files a recommendation. Reversible-internal.
orchestration_pathfinderOpportunity-scout agent: surfaces 2–3 grounded growth opportunities as coworker notes + draft tasks.
orchestration_cairnCodebase-scout agent: ties the biggest telemetry drop-offs to specific source files (needs a connected repo).
orchestration_summitReviewer agent: read-only review of one open PR, filed as findings. Never writes to GitHub.
orchestration_botsCustom bot factory: create / manage per-org persona coworkers on the Workflow chat.

Master Blaster (community boosts)

orchestration_master_blaster_candidatesList feed-post candidates for a boost (engagement / recency / tenure filters). Read-only.
orchestration_master_blaster_splitFire an N-way mutually-exclusive split boost. Dry by default; de-dup + compliance gated.
orchestration_master_blaster_scheduleSchedule a Master Blaster send server-side for a future time.
orchestration_master_blaster_reviewReview weekly-pack / Master Blaster boost performance.

Workflow & collaboration

orchestration_workflowTeam notes / changelog on the Workflow tab.
orchestration_handoffHand a build to a coworker (email + Workflow request: carry-on / QA / launch).
orchestration_projectGroup work into Workflow projects (create / list / archive).
orchestration_taskThe Workflow task tracker.
orchestration_feedbackSend feedback to the TrailGuide team; files a Workflow task + posts to the channel.
orchestration_coachQA + launch the Coach adaptive-onboarding experiment from MCP.
orchestration_deployDeploy the cron runner (orchestration project) from MCP.

Assistant

orchestration_assistantOpen-ended agentic helper over the whole surface.

Example prompts

You don’t call tools directly — you describe intent, Claude composes the calls:

“Connect our Postgres warehouse, discover the schema, and map our billing table to paid status.”
“Build a segment of trial users OR feed commenters in the last week, excluding churned, and size it.”
“Build a segment of paid users inactive 14+ days, size it, and hold it for me.”
“Draft a win-back push in our voice, dry-run it, then show me the render for 5 users.”
“Set the global holdout to 10% and show me lift on the welcome flow over the last 7 days.”
“Hand this campaign off to mel for QA, then launch, and tell her in Slack.”
“What are our biggest activation drop-offs, and where in the app do they happen?”
“Have Pathfinder scout this week’s growth opportunities.”
“Find a strong new-member post from the last 7 days and boost it — dry run first.”
“Query the warehouse for weekly active cooks by plan over the last 8 weeks.”
“Kill all sends now.” (org-wide stop, instantly)

Safety & governance

  • Paused by default. Webhooks install inactive; going live is an explicit toggle / fire.
  • Full send-safety stack. Every fire passes holdouts, frequency caps, exclusions, and the daily gate.
  • Dry run + preview. Size the audience and render real copy before sending one message.
  • Holdout. A global holdout keeps lift measurable; a held-out user is silent everywhere.
  • Kill switch. One call stops every send org-wide.
  • Segments fail closed. A filter that can’t be evaluated for your data resolves to nobody, never the entire audience.
  • Outbound HTTP is SSRF-guarded. An HTTP campaign can only reach a public endpoint; internal, loopback, and cloud-metadata addresses are refused at authoring and again at send time (with DNS-rebinding pinned and every redirect re-checked). Credentials live in auth and are masked on read.
  • Expectations & alerts. Set what “good” looks like per campaign; drift raises an alert.
  • Agents are reversible-internal. The fleet only posts Workflow notes and files draft tasks — it can never send, fire a campaign, change a setting, or write to GitHub.
  • Analysis is read-only. The warehouse, event, Mixpanel, and repo tools are query-only and cost-bounded; they never write.
  • Audited. Every MCP call is attributed to the connected user.

Connect and go

claude mcp add --transport http --scope user trailguide https://trailguide.co/api/personalizer/mcp
Connect Claude