● MCP · Model Context Protocol

Drive GrowthTools from an AI agent

This server exposes your GrowthTools widgets, popups, campaigns and statistics as MCP tools. Claude Desktop, Cursor, Codex, Hermes — or any compatible client — can create a popup, tune its targeting or read its performance in plain language.

Set up in 2 minutes See the 11 tools Read-only

1. How it works

No stored credentials

The server is stateless. Your GrowthTools API key travels with each request and is relayed to the REST API. Nothing is written server-side.

Scoped to your account

Every call runs with your permissions and plan limits. Other customers’ widgets are unreachable.

Draft by default

A widget created by an agent stays disabled until you explicitly ask to publish it.

2. Get your API key

In the dashboard: Account → API. The key is 32 hexadecimal characters and requires a plan with API access enabled (set per plan).

Without a key the MCP returns an explicit error and executes nothing.

3. Configure your client

Endpoint

POST https://dashboard.growthtools.app/mcp/
Authorization: Bearer <your_API_key>
Content-Type: application/json

MCP protocol 2025-06-18, Streamable HTTP transport without sessions. Alternative header: X-GT-API-Key.

Claude Desktop / Cursor / remote-capable clients

{
  "mcpServers": {
    "growthtools": {
      "url": "https://dashboard.growthtools.app/mcp/",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

If your client only accepts command, bridge it locally: npx mcp-remote https://dashboard.growthtools.app/mcp/ --header "Authorization: Bearer YOUR_API_KEY".

Hermes Agent

hermes mcp add growthtools --url https://dashboard.growthtools.app/mcp/ --auth header

# then, in $HERMES_HOME/.env, the variable that header references:
MCP_GROWTHTOOLS_API_KEY=<your_API_key>

Quick check from the command line

curl -s https://dashboard.growthtools.app/mcp/ \
  -H "Authorization: Bearer $GT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

4. Available tools

Tool	Kind	What it does
`gt_capabilities`	read	Server mode, catalogue, quotas, connectivity probe.
`gt_list_types`	read	Widget types and the settings keys each accepts.
`gt_list_campaigns`	read	Campaigns (widget groups) of the account.
`gt_list_widgets`	read	Widgets, filterable by campaign, type, state, name.
`gt_get_widget`	read	One widget and its full settings object.
`gt_get_stats`	read	Impressions, hovers, clicks, submissions.
`gt_create_widget`	write	Creates a draft widget, applies settings, reads the result back.
`gt_update_widget`	write	Patches settings and reports what the server actually kept.
`gt_set_targeting`	write	Mobile / desktop, page rules, trigger, countries, languages, browsers, schedule.
`gt_set_enabled`	write	Publishes or unpublishes a widget.
`gt_delete_widget`	write	Permanently deletes (requires `confirm: true`).

5. Example prompts

“List my active widgets and tell me which one converted best this week.”
“Create a welcome popup on the Main site campaign, title ‘−20% this weekend’, mobile only, after 5 seconds.”
“On widget 412, turn desktop off and restrict it to pages containing /pricing.”
“Compare mobile vs desktop clicks for my five most-seen widgets this month.”

The agent chains tools: gt_list_types → gt_list_campaigns → gt_create_widget → gt_set_targeting, then returns the diff of what changed.

6. Limits and safeguards

Quota: 60 requests / 60 s per API key, shared with your normal dashboard usage.
Abuse guard: this endpoint accepts 120 requests / minute per key.
Writes: disabled on this instance — write tools answer with an explicit refusal.
No preview step: a published widget goes live on the customer site immediately. Keep the draft mode.
Targeting runs in the browser: display_mobile / display_desktop are evaluated by the pixel; the content still ships in the payload.

7. Troubleshooting

`401`	Missing or invalid key, or the account is disabled.
`HTTP 401 — plan_feature_limit`	The plan does not allow API access, or the widget type is not checked in the plan.
`429`	Quota reached: wait a few seconds or batch your reads.
A setting “does not stick”	The server sanitises unknown fields. The response carries `diff.changed`: only those keys were kept.