Verboo Bridge

=18">

verboo-bridge Use modelos da Verboo como sub-agentes no Claude Code, Codex, OpenCode, Cursor ou qualquer cliente MCP Transforme tokens ilimitados da Verboo em execução distribuída para seu orquestrador preferido

---

Arquitetura

graph TB
    subgraph "Orquestrador"
        CLAUDE[Claude Code]
        CODEX[Codex]
        OPENCODE[OpenCode]
        CURSOR[Cursor]
    end

    subgraph "verboo-bridge"
        MCP[Servidor MCPstdio]
        CLI[Wrapper CLIbin/vb]
        AGENT[verboo_agentexecutor por chamada]
        NATIVE[Verboo Code nativoOAuth]
        HARNESS[OpenCodefallback]
    end

    subgraph "Verboo API"
        DS[DeepSeek V4 Flash1M ctx]
        GLM[GLM 5.2197K ctx]
        MIMO[Mimo V2.51M ctx]
        OUTROS[Kimi / Minimax / Qwenvariantes Pro]
    end

    CLAUDE -->|MCP tools| MCP
    CODEX -->|MCP tools| MCP
    CURSOR -->|MCP tools| MCP
    Terminal -->|CLI direta| CLI

    MCP --> AGENT
    AGENT -->|executor: native| NATIVE
    AGENT -->|executor: opencode| HARNESS
    NATIVE -->|OAuth| DS
    HARNESS -->|provider verboo| DS
    OPENCODE -->|provider verboo| DS
    MCP -->|Chave de API| DS
    MCP -->|Chave de API| GLM
    MCP -->|Chave de API| MIMO
    MCP -->|Chave de API| OUTROS
    CLI -->|Chave de API| DS
    CLI -->|Chave de API| OUTROS

---

Modelos disponíveis

| Modelo | Contexto anunciado | Planos | Seleção automática | Ideal para | |--------|--------------------|--------|:-------------------:|-----------| | DeepSeek V4 Flash | 1M | Pro, Max e Ultra | Sim | Codificação geral | | DeepSeek V4 Pro | 1M | Max | Com opt-in | Codificação mais exigente | | Mimo V2.5 | 1M | Pro, Max e Ultra | Sim | Análise com contexto longo | | Mimo V2.5 Pro | 1M | Max | Com opt-in | Análise mais exigente | | GLM 4.7 Flash | 201k | Junior, Pro, Max e Ultra | Sim | Tarefas rápidas | | Qwen 3.6 27B | 262k | Junior, Pro, Max e Ultra | Sim | Tarefas leves | | GLM 5.2 | 197k | Ultra | Sim | Raciocínio complexo | | Kimi K2.7 | 259k | Ultra | Sim | Tarefas gerais e visão | | Minimax M3 | até 1M | Max e Ultra | Sim | Codificação rápida e visão |

Por padrão, o roteador não escolhe automaticamente as variantes exclusivas do Max porque a disponibilidade depende da assinatura. Elas podem ser selecionadas explicitamente por model e limitadas com VERBOO_NATIVE_MODEL_ALLOWLIST. Para incluí-las no ranking automático, defina VERBOO_AUTO_INCLUDE_PREMIUM_MODELS=1; a allowlist, denylist, tier e a política do executor continuam sendo aplicados. Com a variável ausente, 0 ou qualquer outro valor, o comportamento padrão é mantido. O endpoint /models também é filtrado pelo plano associado à chave.

---

Instalação rápida

O bridge e a CLI nativa do Verboo são pacotes separados. Para usar verboo_agent com o executor recomendado:

npm install --global @verboo/code
verboo auth login
verboo auth status --text

Requisitos:

• Node.js 22+ para o executor nativo com @verboo/code;
• Codex, Claude Code, Cursor ou outro cliente MCP;
• OAuth ativo na CLI Verboo — nenhuma API key é necessária no modo nativo.

O bridge pode ser executado diretamente pelo pacote publicado, sem clonar este repositório: npx --yes verboo-bridge@latest. Para desenvolver o bridge localmente, use:

git clone https://github.com/nikolasdehor/verboo-bridge.git
cd verboo-bridge
npm install

Somente o bridge e as ferramentas de API continuam compatíveis com Node.js 18+. O fallback por OpenCode requer OpenCode 1.17.9+.

Variável de ambiente

export VERBOO_AGENT_ALLOWED_ROOTS="/caminho/para/seus/projetos"
# Padrão opcional; cada chamada pode escolher native ou opencode
export VERBOO_AGENT_EXECUTOR="native"
export VERBOO_CODE_BIN="/caminho/para/verboo"
# Opcional: inclui variantes premium/Max no roteamento automático
export VERBOO_AUTO_INCLUDE_PREMIUM_MODELS="1"
# Opcional e sensível: habilita edição (sem shell)
export VERBOO_AGENT_WRITE_ENABLED="1"
# Memória técnica persistente e isolada por projeto
export VERBOO_MEMORY_ENABLED="1"
export VERBOO_MEMORY_DIR="$HOME/.local/share/verboo-bridge/memory"
# Índices curados opcionais, somente leitura
export VERBOO_SHARED_MEMORY_FILES="$HOME/.codex/memories/MEMORY.md:$HOME/ObsidianVaults/ClaudeBrain/MEMORY.md"

Antes do modo nativo, autentique a CLI oficial uma vez com verboo auth login ou verboo auth login --headless. A sessão OAuth é lida pelo subprocesso via diretório do usuário; a API key não é repassada ao executor nativo.

verboo_agent aceita executor: "native" ou executor: "opencode" em cada chamada. A escolha da chamada tem precedência sobre VERBOO_AGENT_EXECUTOR. Sem nenhuma configuração, o padrão é native.

Se o comando verboo não apontar para a CLI oficial, use Node e o entrypoint:

export VERBOO_CODE_BIN="/caminho/para/node"
export VERBOO_CODE_ENTRYPOINT="/caminho/para/@verboo/code/dist/cli.mjs"

VERBOO_API_KEY continua opcionalmente disponível para as ferramentas de prompt simples (verboo_code, verboo_review e ferramentas por modelo). Não grave a chave no repositório.

---

Configuração por plataforma

Em qualquer cliente, o Verboo aparece como uma ferramenta MCP. Ao chamar verboo_agent ou verboo_agent_start, o bridge inicia um subagente externo, separado e ciente do repositório. Ele não aparece como um subagente nativo da interface. read_only e write são apenas modos de permissão dessa execução.

> Em App/IDE ou tarefa não trivial, longa, paralela ou de duração incerta, use > verboo_agent_start, mostre o job_id, continue trabalhando e consulte > verboo_job com status/result. Reserve o verboo_agent síncrono para > tarefas curtas. Se o MCP não aparecer, corrija ou reinicie a integração; não > substitua a chamada por verboo -p, vb, opencode run ou outro shell.

Antes de configurar, descubra os caminhos absolutos:

command -v npx
command -v verboo

No Windows, descubra node.exe e a raiz global do npm pelo PowerShell:

(Get-Command node.exe).Source
npm root --global

Use esses caminhos nos exemplos abaixo. Variáveis, ~ e substituições de comando não são expandidas dentro de JSON ou TOML.

| Cliente | Configuração | Como validar | |---|---|---| | Codex App, CLI e extensão IDE | ~/.codex/config.toml | App/IDE: /mcp; CLI: codex mcp get verboo-bridge | | Claude Desktop | Settings → Developer → Edit Config | Chat: Connectors; logs em ~/Library/Logs/Claude | | Claude Code | claude mcp add ou .mcp.json | claude mcp get verboo-bridge e /mcp | | Cursor IDE e CLI | ~/.cursor/mcp.json ou .cursor/mcp.json | Available Tools ou cursor-agent mcp list-tools verboo-bridge | | OpenCode | opencode.json | opencode mcp list |

Esses clientes iniciam o servidor local por stdio. Apps web ou mobile que não conseguem executar um processo local exigem o transporte HTTP/stateless planejado no P2; essa superfície remota ainda não está implementada.

Codex App, CLI e extensão IDE

O App, a CLI e a extensão compartilham a mesma configuração. Adicione a ~/.codex/config.toml:

[mcp_servers.verboo-bridge]
command = "/caminho/absoluto/para/npx"
args = ["--yes", "verboo-bridge@latest"]
startup_timeout_sec = 60
tool_timeout_sec = 1800
default_tools_approval_mode = "prompt"

[mcp_servers.verboo-bridge.env]
VERBOO_AGENT_ALLOWED_ROOTS = "/caminho/absoluto/para/seus/projetos"
VERBOO_AGENT_EXECUTOR = "native"
VERBOO_CODE_BIN = "/caminho/absoluto/para/verboo"
# Opcional: inclui DeepSeek V4 Pro e Mimo V2.5 Pro no ranking automático
VERBOO_AUTO_INCLUDE_PREMIUM_MODELS = "1"

No Codex App, também é possível abrir Settings → MCP servers → Add server, escolher STDIO e preencher os mesmos valores. Salve e reinicie o App. Na extensão IDE, reinicie a extensão. Consulte a documentação oficial de MCP do Codex.

No Codex App para Windows, instale os dois pacotes uma vez:

npm install --global verboo-bridge@latest @verboo/code

> O CI Windows cobre a suíte de testes, não a integração com o Codex App. > O smoke no Codex App Windows real ainda não foi executado.

Então use os caminhos absolutos retornados pelos comandos acima. Este exemplo evita os shims npx.cmd e verboo.cmd, que não podem ser iniciados diretamente com shell: false:

[mcp_servers.verboo-bridge]
command = 'C:\Program Files\nodejs\node.exe'
args = ['C:\Users\SEU_USUARIO\AppData\Roaming\npm\node_modules\verboo-bridge\index.mjs']
startup_timeout_sec = 60
tool_timeout_sec = 1800
default_tools_approval_mode = "prompt"

[mcp_servers.verboo-bridge.env]
VERBOO_AGENT_ALLOWED_ROOTS = 'C:\Users\SEU_USUARIO\Projects;D:\Work'
VERBOO_JOB_STORE_DIR = 'C:\Users\SEU_USUARIO\AppData\Local\verboo-bridge\jobs'
VERBOO_AGENT_EXECUTOR = "native"
VERBOO_CODE_BIN = 'C:\Program Files\nodejs\node.exe'
VERBOO_CODE_ENTRYPOINT = 'C:\Users\SEU_USUARIO\AppData\Roaming\npm\node_modules\@verboo\code\dist\cli.mjs'

Substitua C:\Program Files\nodejs\node.exe pela saída de (Get-Command node.exe).Source e a raiz C:\Users\SEU_USUARIO\AppData\Roaming\npm\node_modules pela saída de npm root --global. Com nvm-windows, fnm, Volta, Scoop ou um prefixo global customizado, esses caminhos são diferentes.

No Windows, separe múltiplas raízes permitidas com ;. O diretório do store deve ser absoluto: metadados seguros e marcadores de RESTART persistem, mas resultados públicos não são gravados porque o Node não garante uma ACL privada. Eles podem conter código proprietário. npx --yes verboo-bridge@latest continua suportado em terminais e clientes que executam shims .cmd; a configuração direta acima é a opção previsível para o Codex App.

Alternativa pela CLI no macOS ou Linux:

VERBOO_PROJECTS_ROOT="$HOME/Projects"

codex mcp add verboo-bridge \
  --env "VERBOO_AGENT_ALLOWED_ROOTS=$VERBOO_PROJECTS_ROOT" \
  --env "VERBOO_AGENT_EXECUTOR=native" \
  --env "VERBOO_CODE_BIN=$(command -v verboo)" \
  -- "$(command -v npx)" --yes verboo-bridge@latest

codex mcp get verboo-bridge

O comando não adiciona os timeouts e a política de aprovação; complete esses campos no TOML. Se o servidor já existir, não repita o add: edite o bloco existente.

O Codex controla a aprovação da chamada MCP. Para automação não interativa com codex exec, aprove somente as ferramentas necessárias:

[mcp_servers.verboo-bridge.tools.verboo_route]
approval_mode = "approve"

[mcp_servers.verboo-bridge.tools.verboo_agent_start]
approval_mode = "approve"

[mcp_servers.verboo-bridge.tools.verboo_job]
approval_mode = "approve"

Isso evita user cancelled MCP tool call quando não há interface para responder ao prompt. Não use aprovação global irrestrita como atalho.

Para também aprovar verboo_validate, primeiro habilite deliberadamente VERBOO_AGENT_VERIFY_ENABLED=1 no ambiente do bridge. Só então adicione:

[mcp_servers.verboo-bridge.tools.verboo_validate]
approval_mode = "approve"

Sem esse gate, verboo_validate falha fechado.

Claude Desktop

O Claude Desktop está disponível para macOS e Windows. Abra Settings → Developer → Edit Config e edite:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json;
• Windows: %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "verboo-bridge": {
      "command": "/caminho/absoluto/para/npx",
      "args": ["--yes", "verboo-bridge@latest"],
      "env": {
        "VERBOO_AGENT_ALLOWED_ROOTS": "/caminho/absoluto/para/seus/projetos",
        "VERBOO_AGENT_EXECUTOR": "native",
        "VERBOO_CODE_BIN": "/caminho/absoluto/para/verboo"
      }
    }
  }
}

Feche completamente o Claude Desktop e abra novamente. No chat, clique em Add files, connectors, and more → Connectors → Manage connectors e confirme que verboo-bridge está conectado. A configuração segue o guia oficial de servidores MCP locais.

Claude Desktop no Windows com WSL

O Claude Desktop no Windows roda o comando configurado fora da distro WSL. Um padrão comum é apontar command para wsl.exe e usar args com bash -c '...', por exemplo:

{
  "command": "wsl.exe",
  "args": ["bash", "-c", "/home/SEU_USUARIO/.nvm/versions/node/vX.Y.Z/bin/npx --yes verboo-bridge@latest"]
}

Isso costuma falhar com "Server disconnected" sem log útil quando o Node é instalado via nvm. Causa raiz (verificada localmente com env -i, que simula o PATH mínimo de um shell não-login): bash -c abre um shell não-login e não-interativo, que não lê ~/.bashrc nem o init do nvm por padrão. O npx do nvm é um script Node com shebang #!/usr/bin/env node; sem o diretório do nvm no PATH, o env não acha o node e o processo morre na hora, com env: node: No such file or directory (exit 127) antes mesmo de abrir a conexão MCP. O comportamento de bash -c não carregar ~/.bashrc é padrão do Bash em qualquer SO; se o ~/.profile/~/.bash_profile da distro específica encadeia para ~/.bashrc (varia por distro e não foi verificado numa instalação Windows real), isso pode ou não compensar.

Correção recomendada (à prova de PATH, não depende de shell profile): instale o pacote globalmente uma vez, dentro de uma sessão WSL onde npm já funciona, e aponte o Claude Desktop para o wrapper verboo-mcp do pacote, informando o caminho do Node em VERBOO_NODE_BIN:

# uma vez, dentro do WSL
npm install --global verboo-bridge
npm root -g   # confirma o caminho de lib/node_modules

{
  "mcpServers": {
    "verboo-bridge": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-c",
        "VERBOO_NODE_BIN=/home/SEU_USUARIO/.nvm/versions/node/vX.Y.Z/bin/node VERBOO_AGENT_ALLOWED_ROOTS=/caminho/absoluto/para/seus/projetos VERBOO_AGENT_EXECUTOR=native VERBOO_CODE_BIN=/caminho/absoluto/para/verboo exec /home/SEU_USUARIO/.nvm/versions/node/vX.Y.Z/lib/node_modules/verboo-bridge/bin/verboo-mcp"
      ]
    }
  }
}

As variáveis vão dentro do comando, e não no bloco env do claude_desktop_config.json. Aquele bloco define variáveis no ambiente do Windows, e o wsl.exe não as repassa para dentro do WSL sem configurar WSLENV. Declarando antes do exec, elas chegam ao processo Linux que realmente executa o servidor.

O wrapper resolve o interpretador por VERBOO_NODE_BIN antes de qualquer PATH de shell, então nenhuma suposição sobre o profile da distro entra em jogo, e quando o binário informado não existe ele explica a causa no stderr em vez de morrer sem mensagem.

Use o wrapper, e não o index.mjs direto: é ele que carrega o VERBOO_ENV_FILE e exporta a VERBOO_API_KEY antes de subir o servidor. Apontando para o index.mjs, quem guarda as credenciais nesse arquivo fica sem autenticação.

Não use bash -lc como atalho. Parece resolver, mas na instalação padrão do nvm em Ubuntu o init fica no ~/.bashrc, que começa com um early-return para shell não-interativo. Mesmo em shell de login o node continua fora do PATH, e o sintoma é idêntico ao original, o que só dificulta o diagnóstico.

Se você não usa VERBOO_ENV_FILE e prefere invocar o index.mjs sem intermediário, troque o alvo do exec pelo caminho do node seguido do index.mjs instalado, mantendo as variáveis declaradas antes do exec.

Por fim, npx --yes verboo-bridge@latest sempre resolve a versão mais recente do registro e pode baixar o pacote a cada início do cliente MCP, o que soma latência e depende de rede a cada abertura do Claude Desktop. Preferir instalação global (npm install --global verboo-bridge) evita essa resolução de rede repetida e é o caminho mais robusto para uso contínuo.

Claude Code CLI

Para disponibilizar o bridge em todos os projetos no macOS ou Linux:

VERBOO_PROJECTS_ROOT="$HOME/Projects"

claude mcp add --transport stdio --scope user \
  -e "VERBOO_AGENT_

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nikolasdehor](https://github.com/nikolasdehor)
- **Source:** [nikolasdehor/verboo-bridge](https://github.com/nikolasdehor/verboo-bridge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.