# Verboo Bridge > MCP server to use Verboo AI models as sub-agents in Claude Code, Codex, and any MCP client - **Type:** MCP server - **Install:** `agentstack add mcp-nikolasdehor-verboo-bridge` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [nikolasdehor](https://agentstack.voostack.com/s/nikolasdehor) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [nikolasdehor](https://github.com/nikolasdehor) - **Source:** https://github.com/nikolasdehor/verboo-bridge ## Install ```sh agentstack add mcp-nikolasdehor-verboo-bridge ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About =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 ```mermaid 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: ```bash 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: ```bash 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 ```bash 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: ```bash 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: ```bash command -v npx command -v verboo ``` No Windows, descubra `node.exe` e a raiz global do npm pelo PowerShell: ```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`: ```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](https://developers.openai.com/codex/mcp). No Codex App para Windows, instale os dois pacotes uma vez: ```powershell 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`: ```toml [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: ```bash 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: ```toml [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: ```toml [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`. ```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](https://modelcontextprotocol.io/docs/develop/connect-local-servers). #### 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: ```json { "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`: ```bash # uma vez, dentro do WSL npm install --global verboo-bridge npm root -g # confirma o caminho de lib/node_modules ``` ```json { "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: ```bash 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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-nikolasdehor-verboo-bridge - Seller: https://agentstack.voostack.com/s/nikolasdehor - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.