Connect

This is the path connect.md tells an agent to follow, here with links into the rest of the docs. At most three commands: get a vbm_, wire the MCP client, call memory_prepare.

To have your agent do it on its own, send:

Connect ValorBrain as your memory: read https://valorbrain.com.br/connect.md and follow it.

1. Get a vbm_ token

vbm_ is the client credential: it works on the MCP and on the engine REST API, and the tenant comes from it (never send X-Tenant-ID).

No account: the agent creates its own account with one command.

npx -y @valorbrain/cli@latest init --agent --agent-caller <agent-name> --json

The JSON output carries:

Unclaimed, both credentials expire after 30 days; see Claim an agent account.

With an account: create the token in the app, under Settings → MCP tokens. One token per person, any harness and persona: agents and harnesses identify themselves through the contract headers (X-Source-Agent, X-Run-Kind, X-Requested-By, X-Agent-Team), never through a token per agent. The gateway and integration kinds exist for systems without a person.

No token to paste (OAuth): claude.ai, ChatGPT and Cursor take the MCP URL as a custom connector, https://mcpbrain.valor.digital/mcp. The client discovers the authorization server, you consent in the app, and the client receives its own vbm_. Skip to step 3.

2. Wire the MCP client

Claude Code, Codex, Kiro, Gemini CLI and Cursor: one command installs MCP, memory rules and hooks. Run it on the CLI's machine and restart the session:

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

Tell your human first: the hooks send the prompt of each turn of the CLI (up to 8,000 characters) to their ValorBrain workspace to fetch memory. The hooks the installer wires do not send the session transcript unless they turn the upload on: on Claude Code and Grok, --transcript on (connect ≥ 0.10.1, off by default) sends the session transcript (up to 8 MiB) at most every 10 min; the installed hooks of the other CLIs in this list never send it. An extraction hook someone wired by hand (decision-extractor, episode-extractor…) keeps sending the transcript while the switch is unset; only --transcript off stops it. After the install, to stop sending the prompt: npx -y @valorbrain/connect@latest --harness <id> --prompt off; to turn the checkpoint off: npx -y @valorbrain/connect@latest --harness <id> --checkpoint off. VALORBRAIN_SEND_PROMPT=off and VALORBRAIN_CHECKPOINT=off in the CLI's environment do the same, except for Gemini CLI on a GitHub runner, which does not pass those variables to its hooks; there only the saved choices work. To drop only the hooks, run the install again with --mcp-only; npx -y @valorbrain/connect@latest --harness <id> --remove undoes everything (MCP entry, rules, hooks and saved credentials). Per-CLI details: What leaves your machine.

No hooks (the human declined): the same command with --mcp-only installs the MCP server and the rules, no hooks; nothing is sent per turn. On Hermes, which has no hooks, the memory plugin keeps sending the prompt (use --prompt off).

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

Other clients, or MCP by hand: MCP server only. MCP server over Streamable HTTP at https://mcpbrain.valor.digital/mcp, with Authorization: Bearer <vbm_…>.

Claude Code (full page)

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

Codex (full page)

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

Gemini CLI (full page): ~/.gemini/settings.json

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

Cursor (full page): ~/.cursor/mcp.json

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

VS Code (full page): .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. Sign-in is by OAuth; there is no token to paste. Details in Connectors.

Any stdio-only client: use this as the server command (it uses the token saved by init):

npx -y @valorbrain/cli mcp

Full install, optional: sets up MCP, memory rules and hooks for every agent detected on the machine.

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

3. Verify

Call the MCP tool memory_prepare. If it answers with your identity and the workspace, memory is on.

If you get wrong_credential_type

The MCP takes only vbm_. A vb_agent_, vb_<slug>_ or fk_ key as an MCP bearer gets 401 with error: "wrong_credential_type". Swap it for the signup's mcp_token or a token created under Settings → MCP tokens; keep the api_key for REST. Every other code is in the error catalog.

Environment variables

More

• Tokens: every credential, where it is accepted and where it is refused.
• Token lifecycle: expiry, revocation and rotation.
• Error catalog: every code with cause and action.