API · MCP

API and MCP

Connect an AI agent (Cursor, Claude, ChatGPT) to your GuiaFlow account to build tours from screenshots, tweak the copy and publish the permanent link. Pro plan only.

Connect

The MCP server URL is https://app.guiaflow.pro/mcp (Streamable HTTP). With browser sign-in (OAuth) there is no key to copy: the app opens a GuiaFlow page, you sign in and pick the permissions.

One-click install and step-by-step per app: Integrations.

Cursor

Paste into ~/.cursor/mcp.json (or Settings → MCP → Add new MCP server). Cursor asks you to sign in on first use.

{
  "mcpServers": {
    "guiaflow": { "url": "https://app.guiaflow.pro/mcp" }
  }
}

With an API key (no browser sign-in):

{
  "mcpServers": {
    "guiaflow": {
      "url": "https://app.guiaflow.pro/mcp",
      "headers": { "Authorization": "Bearer gf_live_xxxxxxxx" }
    }
  }
}

Claude Code

claude mcp add --transport http guiaflow https://app.guiaflow.pro/mcp

Then run /mcp inside Claude Code and pick guiaflow to sign in.

With an API key (no browser sign-in):

claude mcp add --transport http guiaflow https://app.guiaflow.pro/mcp \
  --header "Authorization: Bearer gf_live_xxxxxxxx"

Claude.ai, Claude Desktop and ChatGPT

In Claude: Settings → Connectors → Add custom connector, paste https://app.guiaflow.pro/mcp and click Connect. In ChatGPT: Settings → Apps & connectors → Developer mode → Create, same URL with OAuth authentication.

VS Code

Paste into .vscode/mcp.json.

{
  "servers": {
    "guiaflow": { "type": "http", "url": "https://app.guiaflow.pro/mcp" }
  }
}

API keys

In the editor, open the account menu → API keys. Name the key, pick permissions and an expiry (30, 90 or 365 days). Keys start with gf_live_ and are shown only once. The same place lets you revoke keys, disconnect apps and see recent activity.

Permissions

tours:read reads tours · tours:write creates and edits · publish publishes and takes down the permanent link · ai writes copy and generates narration with GuiaFlow AI (uses your monthly quota: 100 texts and 30 min of audio) · analytics:read reads link analytics (counts only, no personal data).

MCP tools

ToolPermissionWhat it does
list_tourstours:readLists the account's tours.
get_tourtours:readSteps, theme, lead capture, end CTA and published link.
create_tourtours:writeCreates an empty tour (shows in the editor tagged “created by agent”).
upload_mediatours:writeStores a screenshot (https url or base64) or returns a 15-minute upload URL.
add_step / update_steptours:writeScreenshot, highlight and click (0..1), title, text, narration script.
reorder_steps / delete_steptours:writeReorders or removes steps.
set_themetours:writePreset theme or #RRGGBB colors.
set_lead_capturetours:writeOpening step asking name/email/phone with consent.
set_end_ctatours:writeEnd card with WhatsApp (E.164) and/or an https link.
publishpublishPublishes to the permanent /p link and returns the URL, embed code and the link cover (og:image, rendered on the server). dryRun:true validates and returns preview.url, a preview link valid for 7 days.
unpublishpublishTakes the link down (requires confirm:true).
generate_step_textai + tours:writeThe AI looks at the step screenshot and writes the title and text (and, if asked, the narration script); saves it to the step. 1 text from the quota.
generate_narrationai + tours:writeGenerates the narration (mono 64 kbps MP3) and saves it as the step audio; the step lasts at least as long as the narration. Counts toward the audio quota.
get_analyticsanalytics:readViews, completions, CTA clicks, leads (count), daily series and per-step funnel; without tourId, one summary per link.

Coordinates

Highlight and click use fractions of the image: x, y, width, height between 0 and 1, from the top-left corner. With only click, a highlight is drawn around it. Out-of-range values are clamped and the response says so.

REST API

Base https://app.guiaflow.pro/v1, Authorization: Bearer auth. Full contract in openapi.json. Send Idempotency-Key on POSTs to retry safely.

# 1. criar o tour
curl -s https://app.guiaflow.pro/v1/tours \
  -H "Authorization: Bearer $GUIAFLOW_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-checkout-1" \
  -d '{"name":"Demo do checkout"}'

# 2. um passo por captura (coordenadas em fração 0..1 da imagem)
curl -s https://app.guiaflow.pro/v1/tours/$TOUR/steps \
  -H "Authorization: Bearer $GUIAFLOW_KEY" -H "Content-Type: application/json" \
  -d '{"image":{"url":"https://exemplo.com/tela1.png"},
       "title":"Abra o carrinho","text":"Tudo o que o cliente escolheu fica aqui.",
       "highlight":{"x":0.72,"y":0.05,"width":0.2,"height":0.08},
       "click":{"x":0.82,"y":0.09}}'

# 3. publicar (atualiza o mesmo link nas próximas vezes)
curl -s -X POST https://app.guiaflow.pro/v1/tours/$TOUR/publish \
  -H "Authorization: Bearer $GUIAFLOW_KEY"

# 4. (optional) the AI writes the step copy and narration
curl -s -X POST https://app.guiaflow.pro/v1/tours/$TOUR/steps/$STEP/generate-text \
  -H "Authorization: Bearer $GUIAFLOW_KEY" -H "Content-Type: application/json" -d '{"narrationScript":true}'
curl -s -X POST https://app.guiaflow.pro/v1/tours/$TOUR/steps/$STEP/narration \
  -H "Authorization: Bearer $GUIAFLOW_KEY"

# 5. link analytics (last 30 days)
curl -s https://app.guiaflow.pro/v1/tours/$TOUR/analytics -H "Authorization: Bearer $GUIAFLOW_KEY"

Limits

60 calls per minute per key/app, 600 changes and 30 publishes per hour per account. Images up to 15 MB (PNG, JPEG, WebP, GIF); the published tour up to 12 MB. Responses: 401 invalid or revoked credential, 402 no Pro plan, 403 missing permission, 429 rate limit (see Retry-After).

Security and privacy

We only store hashes of keys and tokens. The usage log (app, action, time, hashed IP) is kept 90 days and shown to you under API keys. Image URLs are fetched only over public https. Details in Privacy.

For agents: Plain-text summary: /llms.txt.