MCP setup

The Crutan MCP server gives agents tool-level access to the platform. It wraps the same REST API the dashboard uses and authenticates with a workspace API key. Plan limits, credit balances, and monthly key spend caps apply on every call.

Prerequisites

A workspace API key (Settings → API & MCP keys) on a plan with API access.
Optional monthly spend cap on the key (UTC calendar month) to bound autonomous API spend.
APP_URL pointing at your Crutan app (e.g. https://app.crutan.com).

Local stdio (Claude Desktop, Cursor)

Best for development. The key lives in your MCP client config — never committed to git.

bash

CRUTAN_API_KEY=crt_… \
APP_URL=https://app.crutan.com \
pnpm --filter @crutan/mcp start

mcp.json (Cursor / Claude)

{
  "mcpServers": {
    "crutan": {
      "command": "pnpm",
      "args": ["--filter", "@crutan/mcp", "start"],
      "env": {
        "CRUTAN_API_KEY": "crt_…",
        "APP_URL": "https://app.crutan.com"
      }
    }
  }
}

Remote HTTP (production)

Streamable HTTP transport at /api/mcp. Each request must include the caller's workspace API key — the server acts as that key, not a shared service key.

Cursor remote MCP

{
  "mcpServers": {
    "crutan": {
      "url": "https://app.crutan.com/api/mcp",
      "headers": {
        "Authorization": "Bearer crt_…"
      }
    }
  }
}

Rate limit: 240 requests/minute per API key. Invalid or missing keys return 401. Exceeding the key's monthly spend cap returns spend_cap_exceeded from the underlying API.

Skill prompts

Skills are MCP prompts — invoke by name to receive a step-by-step playbook. Your agent then calls the primitive tools in order. Also available as resource crutan://skills/catalog.

Prompt	Purpose
`launch-campaign`	Template → import → estimate → generate → verify → report URLs.
`research-and-personalize`	Business context → prospects → generate → QA.
`weekly-conversion-report`	Analytics + hot leads + conversions summary.
`connect-crm`	Webhook → test → confirm delivery.
`onboard-workspace`	Scrape site → business profile → starter template.
`reactivate-cold-leads`	Cold prospects → new angle → relaunch.
`discovery-workflow`	Post-call discovery page end-to-end.

Tools

Billing & limits

Tool	Purpose
`estimate_cost`	Preview cost before spend actions.
`get_entitlements`	Plan limits, credit balances, lock status.
`get_credits`	Recipient, edit, and discovery credit balances.

Templates

Tool	Purpose
`list_templates / get_template`	Browse and fetch templates.
`create_template`	Async AI template build (returns buildId).
`get_template_build`	Poll a create_template build by buildId until completed/failed.
`iterate_template / edit_template`	AI or manual template updates (cost-ack).
`clone_template`	Clone from a public URL.
`list_template_versions / restore_template_version`	Version history.
`set_lead_form`	Lead form + booking config on code templates.

Prospects & batches

Tool	Purpose
`list_prospects / get_prospect / upsert_prospects`	Prospect CRUD (v1).
`import_prospects / remove_prospect`	Bulk import and soft-delete.
`list_batches / get_batch / create_batch`	Batch management — get_batch returns members with page URLs and writeback status.
`batch_status`	Member status counts.
`generate_recipient_batch`	Render pages (cost-ack, async by default).
`regenerate_failed`	Retry failed members.
`verify_batch_ready`	URL + CRM writeback readiness check.
`get_page`	Page metadata by ID.

Analytics & connectors

Tool	Purpose
`get_analytics / get_page_detail`	Workspace and per-page metrics.
`list_hot_leads / list_conversions`	Intent-ranked leads and form submissions.
`list_connectors / create_webhook / test_connector`	Outbound webhooks.

Business context

Tool	Purpose
`get_business_profile / update_business_profile`	Structured business context.
`scrape_business_context`	Fetch a URL, extract business facts, and store them (synchronous).
`get_brand_kit`	Colors, fonts, business profile.

Discovery pages

Tool	Purpose
`create_discovery_session`	Ingest transcript/notes (async).
`get_discovery_session`	Poll status and prospect-voiced questions.
`submit_discovery_answers`	Seller-voice answers.
`build_discovery_page`	Async build (202) — poll until template_id.

Cost acknowledgement: call estimate_cost first, then pass the exact acknowledgedEstimateCents or acknowledgedDiscoveryCredits to spend tools. Async operations (create_template, build_discovery_page, default batch generate) return immediately — poll the matching status endpoint until complete.

Discovery workflow notes

Questions are prospect-voiced (buyer asking about your product). Answers must be seller-voiced.
build_discovery_page returns 202 { buildId, status: "building" } — poll get_discovery_session until status: "completed".
create_template returns 202 { buildId, status: "building" } — poll get_template_build (or list_templates) until status is completed or failed.
get_batch returns each member's url and writeback_status (ok / missing / pending / not_required) — feed those into verify_batch_ready.

← API reference MCP section