Conectar

O caminho canônico até um token vbm_ funcionando: obter o token, ligar o cliente, verificar.

Este é o caminho que o connect.md manda um agente seguir, aqui com os links para o resto das docs. São no máximo três comandos: obter um vbm_, ligar o cliente MCP e chamar memory_prepare.

Para pedir que o seu agente faça tudo sozinho, mande:

Conecte o ValorBrain como sua memória: leia https://valorbrain.com.br/connect.md e siga as instruções.

1. Obter um token `vbm_`

O vbm_ é a credencial do cliente: vale no MCP e no REST do engine, e o tenant vem dele (nunca envie X-Tenant-ID).

Sem conta: o agente cria a conta dele com um comando.

npx -y @valorbrain/cli@latest init --agent --agent-caller <nome-do-agente> --json

A saída JSON traz:

Campo	O que é
`mcp_token`	O token `vbm_…`. Aparece só nesta resposta; a CLI o salva em `~/.valorbrain/config.json`.
`mcp_url`	`https://mcpbrain.valor.digital/mcp`
`api_key`	Chave de conta de agente `vb_agent_…` (legado): só REST e claim. No MCP ela volta `401 wrong_credential_type`.

Sem claim, as duas credenciais expiram em 30 dias; veja Claim de conta de agente.

Com conta: crie o token no app, em Configurações → Tokens MCP. Um token por pessoa, em qualquer harness e persona: agentes e harnesses se identificam pelos cabeçalhos do contrato (X-Source-Agent, X-Run-Kind, X-Requested-By, X-Agent-Team), nunca por um token por agente. Gateway e integração existem para sistemas sem pessoa.

Sem token para colar (OAuth): claude.ai, ChatGPT e Cursor aceitam a URL do MCP como conector personalizado, https://mcpbrain.valor.digital/mcp. O cliente descobre o servidor de autorização, você consente no app e o cliente recebe o próprio vbm_. Pule para o passo 3.

2. Ligar o cliente MCP

Claude Code, Codex, Kiro, Gemini CLI e Cursor: um comando instala MCP, regras de memória e hooks. Rode na máquina da CLI e reinicie a sessão:

npx -y @valorbrain/connect@latest --token <vbm_…> --harness <claude-code|codex|kiro|gemini-cli|cursor>

Antes, avise o humano: os hooks enviam o prompt de cada turno da CLI (até 8.000 caracteres) para o workspace dele no ValorBrain, para buscar a memória. Os hooks que o instalador liga não enviam a transcrição da sessão, a menos que ele ligue o envio: no Claude Code e no Grok, --transcript on (connect ≥ 0.10.1, desligado por padrão) manda o transcript da sessão (até 8 MiB) no máximo a cada 10 min; os hooks instalados das outras CLIs desta lista nunca o enviam. Um hook de extração que alguém ligou à mão (decision-extractor, episode-extractor…) continua enviando o transcript enquanto a chave não for escolhida; só --transcript off impede. Depois da instalação, para parar de enviar o prompt: npx -y @valorbrain/connect@latest --harness <id> --prompt off; para desligar o checkpoint: npx -y @valorbrain/connect@latest --harness <id> --checkpoint off. VALORBRAIN_SEND_PROMPT=off e VALORBRAIN_CHECKPOINT=off no ambiente da CLI fazem o mesmo, menos no Gemini CLI num runner do GitHub, que não passa essas variáveis aos hooks; ali só valem as escolhas salvas. Para tirar só os hooks, rode a instalação de novo com --mcp-only; npx -y @valorbrain/connect@latest --harness <id> --remove desfaz tudo (entrada do MCP, regras, hooks e credenciais salvas). Detalhes por CLI: O que sai da sua máquina.

Sem hooks (o humano recusou): o mesmo comando com --mcp-only instala o servidor MCP e as regras, sem hooks; nada é enviado por turno. No Hermes, que não tem hooks, o plugin de memória continua enviando o prompt (use --prompt off).

npx -y @valorbrain/connect@latest --token <vbm_…> --harness <id> --mcp-only

Outros clientes, ou o MCP à mão: só o servidor MCP. Servidor MCP por Streamable HTTP em https://mcpbrain.valor.digital/mcp, com Authorization: Bearer <vbm_…>.

Claude Code (página completa)

claude mcp add --transport http --scope user valorbrain https://mcpbrain.valor.digital/mcp --header "Authorization: Bearer <vbm_…>"

Codex (página completa)

export VALORBRAIN_MCP_TOKEN=<vbm_…>
codex mcp add valorbrain --url https://mcpbrain.valor.digital/mcp --bearer-token-env-var VALORBRAIN_MCP_TOKEN

Gemini CLI (página completa): ~/.gemini/settings.json

{"mcpServers":{"valorbrain":{"httpUrl":"https://mcpbrain.valor.digital/mcp","headers":{"Authorization":"Bearer <vbm_…>"}}}}

Cursor (página completa): ~/.cursor/mcp.json

{"mcpServers":{"valorbrain":{"url":"https://mcpbrain.valor.digital/mcp","headers":{"Authorization":"Bearer <vbm_…>"}}}}

VS Code (página completa): .vscode/mcp.json

{"servers":{"valorbrain":{"type":"http","url":"https://mcpbrain.valor.digital/mcp","headers":{"Authorization":"Bearer <vbm_…>"}}}}

claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → URL https://mcpbrain.valor.digital/mcp. O login é por OAuth; não há token para colar. Detalhes em Conectores.

Qualquer cliente que só fala stdio: use como comando do servidor (usa o token salvo pelo init):

npx -y @valorbrain/cli mcp

Instalação completa, opcional: configura MCP, regras de memória e hooks em todos os agentes detectados no computador.

npx -y @valorbrain/connect@latest --token <vbm_…>

3. Verificar

Chame a ferramenta MCP memory_prepare. Se ela responder com a sua identidade e o workspace, a memória está ligada.

Se der `wrong_credential_type`

O MCP aceita só vbm_. Uma chave vb_agent_, vb_<slug>_ ou fk_ como bearer no MCP volta 401 com error: "wrong_credential_type". Troque pelo mcp_token do signup ou por um token criado em Configurações → Tokens MCP; a api_key fica para o REST. Os outros códigos estão no catálogo de erros.

Variáveis de ambiente

Variável	Guarda
`VALORBRAIN_MCP_TOKEN`	Token `vbm_`
`VALORBRAIN_API_KEY`	Chave REST `vb_agent_`
`VALORBRAIN_API_URL`	`https://valorbrain-api.valor.digital`
`VALORBRAIN_MCP_URL`	`https://mcpbrain.valor.digital/mcp`

Mais

Tokens: cada credencial, onde é aceita e onde é recusada.
Ciclo de vida dos tokens: validade, revogação e rotação.
Catálogo de erros: cada código com causa e ação.

1. Obter um token vbm_