MCP Tool Reference

WisePilot exposes its full surface area through 8 domain pairs ({domain}_explore + {domain}_query) plus 4 atomic orchestration tools. This is the recommended way to use the MCP server from Claude, ChatGPT projects, or any MCP client — the agent discovers operations dynamically rather than memorizing 100+ individual tool names.

The legacy atomic tools (e.g. get_conversation_metrics, list_assets, list_ad_creatives) are still registered and continue to work. New integrations should prefer the explore/query pattern below — it scales better as we add capabilities.

How It Works

Every domain has the same two tools:

{domain}_explore — browse what’s available. Returns a category list with operation counts. Drill into a category to see operations with full param schemas + examples.
{domain}_query — execute one operation. Takes { operation, params }.

# 1. See what the metrics domain offers
metrics_explore()

# 2. Drill into one category
metrics_explore({ category: "engagement" })

# 3. Execute an operation
metrics_query({
  operation: "conversation",
  params: { website_id: "abc-123", period: "30d" }
})

The agent only needs to remember 16 tool names (8 explore + 8 query) rather than 100+ atomic tools, and discovery is self-documenting.

The 8 Domains

intelligence

Lifecycle state, work items, content opportunities, AI insights, hypothesis test runs, confirmed learnings, pattern candidates, attribution rollups, runner stats. 12 ops across 4 categories.

metrics

GHL conversations / appointments / revenue, Google + Meta Ads, GSC, GA4, GBP, content/CTA performance, client snapshot. 22 ops across 6 categories.

Google Ads + Meta Ads catalog and performance: creatives, ad sets, keywords, search terms, daily timeseries, summaries. 10 ops across 3 categories.

content

Library reads: assets, blogs, CTAs, nurture sequences, sequence steps, entities, opportunities, full-text search. 10 ops across 4 categories.

brand

Brand position, guidelines, ICPs, hooks & angles, messaging learnings, operating profile, design tokens, color palettes, image styles, brand subjects. 10 ops across 2 categories.

ghl

GHL CRM browse: conversations + messages, appointments, pipeline stages, opportunities. 5 ops across 3 categories.

seo_research

Ahrefs-backed: keyword ideas, bulk metrics, SERP analysis, competitor keywords. Each call consumes Ahrefs credits. 4 ops across 2 categories.

integration

Connection state (WordPress, GHL, ad platforms), GHL agents/prompts/KBs/contacts, ad campaigns, sync trigger. 7 ops across 4 categories.

The 4 Atomic Orchestration Tools

These are stateful or composed actions that don’t fit the “browse + execute” pattern.

`dispatch_lifecycle`

Open or resume a content lifecycle session. Given a content type and intent, returns a chat session id, the current step, the chat hint for that step, and a deep-link URL.

dispatch_lifecycle({
  entity_type: "blog",
  intent: "create",
  inputs: { title: "Outdoor wedding venues", primary_keyword: "wedding venue houston" }
})
// → { session_id, current_step, chat_hint, deep_link_url }

Intents: create (new entity), edit (resume edit lifecycle), optimize (ad ops), review (approval review), approve (approval gate). Permission: write_staging (or approve for intent: "approve").

`promote_learning`

Promote a pattern_candidate to a durable confirmed_learning. Human-in-the-loop step at the end of the hypothesis-iteration pipeline.

promote_learning({
  pattern_candidate_id: "uuid-here",
  summary: "Hooks that lead with 'the moment' outperform feature-led hooks by 35-50% on Meta carousel ads."
})
// → { confirmed_learning_id, pattern_candidate_id, ... }

Guards: win_count >= 2, avg_confidence >= 0.6, no active duplicate (overrideable). Permission: approve.

`request_wp_engineer_work`

File an engineering task into the unified inbox under label='engineer_work'. Use this when the agent identifies a problem requiring WP / theme / plugin / infra changes (not a content edit).

request_wp_engineer_work({
  title: "Tracking pixel missing on /pricing",
  description: "Confirmed via GTM preview that the meta_lead_pixel is not firing on /pricing. We need to add it to the page template before launch...",
  priority: "high",
  area: "tracking",
  reference_url: "https://example.com/pricing"
})
// → { work_item_id, label: "engineer_work", priority, area }

Permission: write_staging.

`get_image_brief`

Composed read returning a brand-aligned brief that any image-gen client (ChatGPT’s built-in image gen, Claude’s image renderer) can hand off. Bundles brand position + design tokens + color palette + image style + brand subjects + suggested prompt prefix + do/don’t lists.

get_image_brief({
  intent: "Hero for a blog about outdoor wedding venues in Houston",
  preset: "blog_hero"  // square | portrait | landscape | story | meta_feed | meta_story | blog_hero
})
// → { intent, dimensions, brand_position, design_tokens, color_palette, image_style, brand_subjects, do, dont, prompt_prefix }

For server-side image generation (lifecycle-attached, persisted), use the legacy generate_image tool. Permission: read.

Permission Scopes

API keys carry one or more permissions. Each operation declares which it requires; the MCP server returns 403 PERMISSION_DENIED when missing.

Permission	Use cases
`read`	All `_explore` calls and read-only `_query` operations.
`write_staging`	Create / update entities in staging state — e.g. `intelligence_query` `create_work_item`, `dispatch_lifecycle`, `request_wp_engineer_work`.
`push`	Actions that change external systems — e.g. `integration_query` `trigger_sync`, the legacy `push_to_platform_rest`.
`approve`	Approval / promotion gates — e.g. `promote_learning`, approving work items via `dispatch_lifecycle({intent:"approve"})`.

Existing pre-v1 keys are auto-granted all four permissions for backward compatibility. New keys can be scoped to a subset (read-only, write-staging-no-approve, etc).

Authentication

The MCP endpoint at https://ai.wisepilot.app/api/v1/mcp accepts:

OAuth 2.1 + PKCE — Claude.ai, Claude Desktop, Claude Code use this. Identity-tied, automatic refresh.
API key (Bearer) — ChatGPT projects, custom MCP clients, scripts. Authorization: Bearer cr_.... Created in Settings → API Keys.

API keys can also carry an expires_at and a monthly image-gen budget counter, both enforced at the middleware layer.

Common Patterns

Discovery before execution

When unsure which operation to call, always _explore first.

# Explore overview → pick a category → drill in → execute
metrics_explore()
metrics_explore({ category: "seo" })
metrics_query({ operation: "gsc_pages", params: { website_id, period: "30d", limit: 50 } })

Date ranges (metrics, ads, ghl)

All time-bounded operations accept the same shape:

{
  period: "today" | "7d" | "30d" | "90d" | "mtd" | "ytd"  // default 30d
  // OR
  start_date: "2026-04-01",
  end_date: "2026-04-15"  // overrides period
}

Pagination

limit + offset on every list-style op. Defaults to 50 items, max 200 for most operations. SEO research and image briefs cap differently — see explore output for per-op limits.

Error shapes

Every error returns a structured payload the LLM can parse:

{
  "error": "limit: must be an integer",
  "code": "INVALID_PARAMS",
  "field": "limit"
}

Common codes: INVALID_PARAMS, UNKNOWN_OPERATION, PERMISSION_DENIED, MISSING_WEBSITE_SCOPE, FORBIDDEN_WEBSITE, RATE_LIMIT_EXCEEDED, API_KEY_EXPIRED.

Migration from atomic tools

If you have an existing integration using the per-tool API (e.g. get_conversation_metrics, list_ad_creatives):

Old atomic tool	New equivalent
`get_conversation_metrics`	`metrics_query({operation:"conversation"})`
`get_appointment_metrics`	`metrics_query({operation:"appointment"})`
`get_revenue_metrics`	`metrics_query({operation:"revenue"})`
`get_gsc_pages`	`metrics_query({operation:"gsc_pages"})`
`get_gsc_queries`	`metrics_query({operation:"gsc_queries"})`
`list_assets`	`content_query({operation:"assets"})`
`get_asset_detail`	`content_query({operation:"asset_detail"})`
`list_ad_creatives`	`ads_query({operation:"creatives"})`
`get_brand_position`	`brand_query({operation:"position"})`
`get_design_tokens`	`brand_query({operation:"design_tokens"})`
`list_conversations`	`ghl_query({operation:"list"})`
`get_keyword_ideas`	`seo_research_query({operation:"keyword_ideas"})`
`get_work_items`	`intelligence_query({operation:"work_items"})`
`get_lifecycle_status`	`intelligence_query({operation:"lifecycle_state"})`
`trigger_integration_sync`	`integration_query({operation:"trigger_sync"})`

The legacy tools remain registered — there’s no rush. Migrate when you’re updating the integration anyway.

Reference

Strategy doc: docs/mcp-tool-surface-strategy.md (rationale, design decisions, future domains)
Reference implementation: /Code/base-microservices/apps/open-data/ — the proven explore/query pattern this is based on
Source: src/features/public-api/server/mcp/router/ (generic dispatcher) and src/features/public-api/server/mcp/domains/* (one folder per domain)

Getting Started

Platform Integrations

HighLevel CRM

AI Assistants

MCP Tool Reference

How It Works

The 8 Domains

intelligence

metrics

ads

content

brand

ghl

seo_research

integration

The 4 Atomic Orchestration Tools

`dispatch_lifecycle`

`promote_learning`

`request_wp_engineer_work`

`get_image_brief`

Permission Scopes

Authentication

Common Patterns

Discovery before execution

Date ranges (metrics, ads, ghl)

Error shapes

Migration from atomic tools

Reference

​How It Works

​The 8 Domains

intelligence

metrics

ads

content

brand

ghl

seo_research

integration

​The 4 Atomic Orchestration Tools

​dispatch_lifecycle

​promote_learning

​request_wp_engineer_work

​get_image_brief

​Permission Scopes

​Authentication

​Common Patterns

​Discovery before execution

​Date ranges (metrics, ads, ghl)

​Pagination

​Error shapes

​Migration from atomic tools

​Reference

How It Works

The 8 Domains

The 4 Atomic Orchestration Tools

`dispatch_lifecycle`

`promote_learning`

`request_wp_engineer_work`

`get_image_brief`

Permission Scopes

Authentication

Common Patterns

Discovery before execution

Date ranges (metrics, ads, ghl)

Pagination

Error shapes

Migration from atomic tools

Reference