Woovi | Dúvidas Frequentes (FAQ)

Como conectar a Woovi ao Claude Code, Cursor, Codex e VS Code com o MCP

Abrir em
Ver como Markdown Abrir no ChatGPT Abrir no Claude
Gilberto Filho

Gilberto Filho

Última atualização em Sep 25, 2026

O MCP (Model Context Protocol) da Woovi permite que assistentes de IA consultem e operem sua conta Woovi em seu nome. Com ele, você pode pedir ao assistente coisas como "liste as cobranças pagas hoje" ou "crie uma cobrança de R$ 50 para o cliente João", sem precisar escrever código de integração.

O acesso é feito com login na Woovi e autorização explícita: você escolhe a conta e as permissões (scopes) que o assistente pode usar, e pode revogar o acesso a qualquer momento.

1. Endereço do servidor MCP

Todos os clientes usam o mesmo endereço:

https://mcp.woovi.com/mcp

O servidor usa transporte HTTP e autenticação OAuth. Você não precisa gerar AppID nem copiar tokens: o login acontece no navegador na primeira conexão.

2. Instalando no Claude Code

No terminal, rode:

claude mcp add --transport http --client-id claude-code woovi https://mcp.woovi.com/mcp

Depois, abra o Claude Code, digite /mcp, selecione o servidor woovi e escolha autenticar. O navegador abrirá a tela de login da Woovi.

Para disponibilizar o servidor em todos os seus projetos, adicione --scope user ao comando.

3. Instalando no Cursor

Edite o arquivo ~/.cursor/mcp.json (vale para todos os projetos) ou .cursor/mcp.json na raiz do projeto:

{
  "mcpServers": {
    "woovi": {
      "url": "https://mcp.woovi.com/mcp",
      "auth": {
        "CLIENT_ID": "cursor"
      }
    }
  }
}

Salve o arquivo, abra Settings > MCP no Cursor e clique para conectar o servidor woovi. O navegador abrirá a tela de login da Woovi.

4. Instalando no Codex

No terminal, rode:

codex mcp add woovi --url https://mcp.woovi.com/mcp --oauth-client-id codex
codex mcp login woovi

Se preferir editar a configuração manualmente, adicione ao arquivo ~/.codex/config.toml:

[mcp_servers.woovi]
url = "https://mcp.woovi.com/mcp"

[mcp_servers.woovi.oauth]
client_id = "codex"

Depois, rode codex mcp login woovi para fazer o login no navegador. Dentro do Codex, o comando /mcp mostra o status da conexão.

5. Instalando no VS Code

No VS Code (modo agente do GitHub Copilot), crie o arquivo .vscode/mcp.json no projeto, ou abra a configuração global com o comando "MCP: Open User Configuration":

{
  "servers": {
    "woovi": {
      "type": "http",
      "url": "https://mcp.woovi.com/mcp",
      "oauth": {
        "clientId": "vscode"
      }
    }
  }
}

Clique em Start, que aparece acima do servidor no arquivo mcp.json. O navegador abrirá a tela de login da Woovi.

6. Autorizando o acesso na Woovi

Na primeira conexão, o navegador abre a Woovi:

  • Faça login com seu usuário da Woovi.

  • Se sua empresa tiver mais de uma conta, escolha a conta em que o assistente vai atuar.

  • Revise as permissões na tela "Conectar à Woovi" e desmarque as que você não quer conceder.

  • Clique em Permitir.

As permissões aparecem em duas abas: Visualizar (somente leitura) e Criar e alterar (escrita). Você pode selecionar tudo, um grupo inteiro ou permissões individuais. Ao final, o navegador volta para o seu editor e as ferramentas da Woovi ficam disponíveis.

7. Permissões (scopes) e ferramentas disponíveis

Cada ferramenta do MCP exige um scope. Se você não conceder o scope, o assistente não consegue usar a ferramenta correspondente.

Visualizar (leitura):

  • COMPANY_GET: consultar os dados da empresa.

  • ACCOUNT_GET_LIST e ACCOUNT_GET: listar e consultar contas.

  • ACCOUNT_LIMITS_GET: consultar os limites da conta.

  • CHARGE_GET_LIST e CHARGE_GET: listar e consultar cobranças.

  • TRANSACTION_GET_LIST e TRANSACTION_GET: listar e consultar transações.

  • CUSTOMER_GET_LIST e CUSTOMER_GET: listar e consultar clientes.

  • WEBHOOK_GET_LIST: listar webhooks.

  • WEBHOOK_EVENTS_GET_LIST: listar eventos de webhook.

  • DISPUTE_GET_LIST e DISPUTE_GET: listar e consultar disputas.

  • SUBSCRIPTION_GET_LIST e SUBSCRIPTION_GET: listar e consultar assinaturas.

  • SUBSCRIPTION_INSTALLMENT_GET_LIST e SUBSCRIPTION_INSTALLMENT_GET: listar e consultar parcelas de assinatura.

Criar e alterar (escrita):

  • CHARGE_POST: criar cobrança.

  • CHARGE_DELETE: excluir cobrança.

  • CUSTOMER_POST: criar cliente.

  • CUSTOMER_PATCH: atualizar cliente.

  • PIX_QRCODE_POST: criar QR Code Pix estático.

Dica: conceda apenas o que você vai usar. Para um assistente que só consulta dados, marque somente a aba Visualizar.

8. Limites de uso

Para proteger sua conta, cada ferramenta de leitura pode ser chamada até 60 vezes por minuto, e cada ferramenta de escrita até 20 vezes por minuto. Se o limite for atingido, aguarde alguns segundos e tente novamente.

9. Vendo e revogando os assistentes conectados

Você pode ver os assistentes conectados e desconectá-los a qualquer momento em qualquer um destes lugares:

Localize o cliente (Claude Code, Cursor, Codex ou VS Code) e clique em Desconectar. O acesso é encerrado na hora.