API · MCP

API e MCP

Conecte um agente de IA (Cursor, Claude, ChatGPT) à sua conta GuiaFlow para criar tours a partir de capturas de tela, ajustar textos e publicar o link permanente. Exclusivo do plano Pro.

Conectar

O endereço do servidor MCP é https://app.guiaflow.pro/mcp (Streamable HTTP). Pelo login no navegador (OAuth) não há chave para copiar: o app abre a página do GuiaFlow, você entra e escolhe as permissões.

Instalação em um clique e passo a passo por app: Integrações.

Cursor

Cole em ~/.cursor/mcp.json (ou Settings → MCP → Add new MCP server). Na primeira chamada o Cursor pede o login.

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

Com chave de API (sem login no navegador):

{
  "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

Depois rode /mcp dentro do Claude Code e escolha guiaflow para entrar.

Com chave de API (sem login no navegador):

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

Claude.ai, Claude Desktop e ChatGPT

No Claude: Configurações → Conectores → Adicionar conector personalizado, cole https://app.guiaflow.pro/mcp e clique em Conectar. No ChatGPT: Configurações → Apps e conectores → Modo desenvolvedor → Criar, com a mesma URL e autenticação OAuth.

VS Code

Cole em .vscode/mcp.json.

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

Chaves de API

No editor, abra o menu da conta → Chaves de API. Dê um nome, escolha as permissões e a validade (30, 90 ou 365 dias). A chave começa com gf_live_ e aparece uma vez só. No mesmo lugar você revoga chaves, desconecta apps e vê os últimos usos.

Permissões

tours:read lê tours · tours:write cria e edita · publish publica e tira do ar o link permanente · ai escreve textos e gera narração com a IA do GuiaFlow (usa a sua cota mensal: 100 textos e 30 min de áudio) · analytics:read lê as estatísticas dos links (só contagens, sem dados pessoais).

Ferramentas do MCP

FerramentaPermissãoO que faz
list_tourstours:readLista os tours da conta.
get_tourtours:readPassos, tema, captura de lead, CTA final e link publicado.
create_tourtours:writeCria um tour vazio (aparece no editor com a etiqueta “criado por agente”).
upload_mediatours:writeGrava uma captura (url https ou base64) ou devolve uma URL de upload de 15 min.
add_step / update_steptours:writeCaptura, destaque e clique (0..1), título, texto, roteiro de narração.
reorder_steps / delete_steptours:writeReordena ou remove passos.
set_themetours:writeTema pronto ou cores #RRGGBB.
set_lead_capturetours:writePasso inicial com nome/e-mail/telefone e consentimento (LGPD).
set_end_ctatours:writeCartão final com WhatsApp (E.164) e/ou link https.
publishpublishPublica no link permanente /p e devolve URL, embed e a capa do link (og:image, gerada no servidor). dryRun:true valida e devolve preview.url, um link de prévia que vale 7 dias.
unpublishpublishTira o link do ar (exige confirm:true).
generate_step_textai + tours:writeA IA olha a captura do passo e escreve título e texto (e, se pedir, o roteiro da narração); grava no passo. 1 texto da cota.
generate_narrationai + tours:writeGera a narração (MP3 mono 64 kbps) e grava como áudio do passo; o passo passa a durar a narração. Conta na cota de áudio.
get_analyticsanalytics:readVisualizações, conclusões, cliques no CTA, leads (contagem), série por dia e funil por passo; sem tourId, um resumo por link.

Coordenadas

Destaque e clique usam fração da imagem: x, y, width, height entre 0 e 1, a partir do canto superior esquerdo. Só com click, o destaque é criado em volta. Valores fora do intervalo são ajustados e o retorno avisa.

API REST

Base https://app.guiaflow.pro/v1, autenticação Authorization: Bearer. Contrato completo em openapi.json. Envie Idempotency-Key nos POST para repetir com segurança.

# 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. (opcional) IA escreve o texto e a narração do passo
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. estatísticas do link (últimos 30 dias)
curl -s https://app.guiaflow.pro/v1/tours/$TOUR/analytics -H "Authorization: Bearer $GUIAFLOW_KEY"

Limites

60 chamadas por minuto por chave/app, 600 alterações e 30 publicações por hora por conta. Imagens até 15 MB (PNG, JPEG, WebP, GIF); o tour publicado até 12 MB. Respostas: 401 credencial inválida ou revogada, 402 sem plano Pro, 403 sem a permissão, 429 limite (veja Retry-After).

Segurança e privacidade

Guardamos só o hash das chaves e tokens. O registro de uso (app, ação, horário, IP em hash) fica 90 dias e aparece para você em Chaves de API. URLs de imagem são baixadas só via https público. Detalhes em Privacidade.

Para agentes: Resumo em texto puro: /llms.txt.