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:

* No painel da Woovi: <https://app.woovi.com/home/applications/tab/mcp>

* Na tela de conexões da conta Woovi: <https://auth.woovi.com/mcp/connections>

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