Tools

Discovery (metadados)

Tool	Quando usar
`list_specs`	Ver versões OpenAPI (`v1`, futuro `v2`)
`list_operations`	Listar todos os `operationId` (filtro por `tag`)
`get_operation`	Schema completo de uma operação
`search_operations`	Buscar por nome, path ou descrição
`execute_operation`	Executar qualquer operação por `operationId`

execute_operation

Execução sempre por operationId — nunca por path/method cru:

{
  "operationId": "createPaymentPix",
  "body": { "amount": 100, "description": "Pedido 123" },
  "pathParams": {},
  "query": {},
  "paginate": false,
  "idempotencyKey": "opcional-uuid"
}

Resposta HAR-like:

{
  "request": { "method": "POST", "url": "...", "headers": { "X-API-Key": "[REDACTED]" } },
  "response": { "status": 200, "headers": {}, "body": {} },
  "durationMs": 52,
  "rateLimit": { "remaining": 98, "limit": 100 }
}

Paginação automática

Endpoints com page + limit aceitam paginate: true:

{
  "operationId": "listPaymentPix",
  "paginate": true,
  "maxPages": 10
}

Tools auto-geradas

Cada operationId do OpenAPI v1 é registrado como tool individual no startup — 101 tools atualmente. Exemplos: createPaymentPix, getAccountBalance, createWebhook, listStoreProducts. Mudou o OpenAPI → rebuild do MCP → tools atualizam automaticamente. Validação via Ajv (zero schema duplicado).

Documentação

Tool	Descrição
`search_docs`	Busca no índice local; filtro opcional `topic`: `bot`, `websocket`, `webhook`, `pix`, `store`
`fetch_doc`	Markdown completo por `id`
`recommend_integration_mode`	Recomenda WebSocket vs webhook — ideal para bots Discord/Telegram

recommend_integration_mode

{
  "platform": "discord",
  "hasPublicHttps": false,
  "description": "bot de venda com cargo VIP"
}

Retorna recommended (websocket | webhook | backend-only), passos e resources MCP relacionados.

Ferramentas compostas

Resolvem tarefas completas em uma chamada:

Tool	Fluxo interno
`debug_api_key`	Testa auth → saldo → listagem PIX
`configure_webhook`	Valida HTTPS → registra → retorna `secret`
`create_checkout`	Produto → payment link → URL de checkout
`analyze_webhook`	Explica payload + HMAC (sem API key)

Resources

URI	Conteúdo
`WovePay://spec/v1`	OpenAPI completo
`WovePay://docs`	Índice llms.txt
`WovePay://examples`	JSONs de exemplo
`WovePay://webhooks`	Guia de webhooks
`WovePay://websocket`	Protocolo WebSocket
`WovePay://websocket-pratica`	Tutorial WebSocket passo a passo
`WovePay://bots-playbook`	Matriz bot / webhook / WebSocket
`WovePay://playbook/bots`	Mesmo playbook (alias)
`WovePay://errors`	Tabela de erros HTTP
`WovePay://changelog`	Changelog

Bots — fluxo recomendado

recommend_integration_mode com platform: discord (ou telegram/whatsapp)
Ler WovePay://bots-playbook
createPaymentPix com externalReference único
WebSocket wss://ws.WovePay.com.br/v1 → subscribe payment.*
Entregar produto no payment.paid + ack

Retry e rate limit

Retry automático em 429, 500, 502, 503 (backoff exponencial, max 3)
Respeita header Retry-After
Rate limit da API: 100 req/min por key — veja rateLimit na resposta HAR

Começar

Configurar

Referência

Discovery (metadados)

execute_operation

Paginação automática

Tools auto-geradas

Documentação

recommend_integration_mode

Ferramentas compostas

Resources

Bots — fluxo recomendado

Retry e rate limit

​Discovery (metadados)

​execute_operation

​Paginação automática

​Tools auto-geradas

​Documentação

​recommend_integration_mode

​Ferramentas compostas

​Resources

​Bots — fluxo recomendado

​Retry e rate limit

Discovery (metadados)

execute_operation

Paginação automática

Tools auto-geradas

Documentação

recommend_integration_mode

Ferramentas compostas

Resources

Bots — fluxo recomendado

Retry e rate limit