Conceitos
Hosts
REST, MCP e o app são três hostnames com três funções. Misturá-los é a falha de integração mais comum.
| Hostname | Função | O que acontece se você errar |
|---|---|---|
valorbrain-api.valor.digital | REST — /search, /documents, /api/v1/agents/*, /health | É o --url padrão da CLI. |
mcpbrain.valor.digital | MCP — /mcp, descoberta OAuth | Todo caminho não-OAuth é tratado como transporte MCP e devolve 401 missing_bearer. /search aqui não busca. |
valorbrain.valor.digital | App SaaS — UI, /api/v1/ingest com chaves fk_, /llms.txt (marketing), conectores | O OpenAPI de marketing aqui tem 4 paths. Não é a spec do engine. |
docs.valor.digital | Esta documentação | llms.txt / llms-full.txt gerados. O docs.valorbrain.valor.digital aninhado precisa de ACM. |
A descoberta OAuth (/.well-known/oauth-authorization-server) funciona no host
MCP. O Dynamic Client Registration (POST /oauth/register) também funciona lá.
localhost:7438 é o engine na máquina que o executa. Não é uma URL
pública. O engine costumava anunciá-lo em /setup/instructions; isso foi
corrigido em 2026-08-30 (VALORBRAIN_PUBLIC_URL agora aponta para
valorbrain-api).
Regra
- CLI de agente e qualquer cliente REST →
valorbrain-api - Cliente MCP →
mcpbrain(HTTP) ou@valorbrain/connect(stdio) - Usuário no navegador →
valorbrain.valor.digital