Guia de Configuração MCP

Como conectar clientes MCP à Memory API do Context OS.

Endpoint MCP

A Memory API expõe endpoints MCP (Model Context Protocol) por banco de memória. O padrão de URL é:

https://memory.bonnano.com.br/mcp/<bank-id>/

Bancos disponíveis:

andre-global — banco de memória global pessoal
context-os — banco do sistema operacional de contexto

Exemplo completo: https://memory.bonnano.com.br/mcp/context-os/

Autenticação

A autenticação via Bearer token é obrigatória para todas as requisições. Requisições sem token válido recebem resposta 401 Unauthorized.

Header de autenticação

Authorization: Bearer <YOUR_API_TOKEN>

No servidor, o token é definido pela variável de ambiente HINDSIGHT_API_TENANT_API_KEY. Para clientes, utilize a variável MEMORY_API_TOKEN.

⚠ Segurança: Nunca faça commit de tokens no git. Utilize variáveis de ambiente ou gerenciadores de segredos (secret managers) para armazenar credenciais.

Operações MCP

O servidor MCP expõe as seguintes operações (tools):

`retain` assíncrono

Armazena memória de forma assíncrona. O servidor aceita a requisição e processa em background. Ideal para fluxos onde a confirmação imediata não é necessária. O processamento inclui extração de fatos, resolução de entidades e indexação vetorial.

`sync_retain` síncrono

Versão síncrona do retain. Bloqueia até o processamento completo. Use quando precisar de confirmação de que a memória foi totalmente processada antes de prosseguir.

`recall` leitura

Busca memórias por relevância semântica, temporal ou baseada em grafo. Aceita query em linguagem natural.

`reflect` leitura

Gera reflexões e insights sobre memórias armazenadas. Útil para consolidar aprendizados, detectar padrões e gerar resumos.

Configuração para OpenClaw/Marvin

Para integrar com o OpenClaw (agente Marvin), adicione a seguinte configuração MCP:

{
  "mcp": {
    "servers": {
      "context-os": {
        "url": "https://memory.bonnano.com.br/mcp/context-os/",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${MEMORY_API_TOKEN}"
        }
      }
    }
  }
}

Defina a variável de ambiente MEMORY_API_TOKEN com o token de acesso antes de iniciar o cliente. A variável será interpolada automaticamente na configuração.

Configuração para Clientes MCP Genéricos

Clientes compatíveis com MCP — como Claude Desktop, Cursor, Windsurf e outros — podem utilizar o seguinte formato de configuração:

{
  "mcpServers": {
    "hindsight-memory": {
      "url": "https://memory.bonnano.com.br/mcp/<bank-id>/",
      "headers": {
        "Authorization": "Bearer ${MEMORY_API_TOKEN}"
      }
    }
  }
}

Substitua <bank-id> pelo banco desejado (andre-global ou context-os).

Segurança

Criptografia em trânsito: todo tráfego é protegido por HTTPS/TLS, terminado automaticamente pelo Caddy.
Autenticação obrigatória: requisições sem token válido retornam 401 Unauthorized.
Isolamento lógico de bancos: cada endpoint é vinculado ao bank indicado na URL. Nesta implantação, a credencial Bearer é compartilhada e deve ser tratada como acesso privilegiado.
Serviços internos não expostos: PostgreSQL (porta 5432) e Control Plane (porta 9999) não são acessíveis pela internet.
Painel protegido: o Control Plane está disponível em /panel/, com chave de acesso própria e sem publicar a porta interna 9999.
Segredos protegidos: credenciais ficam em /opt/context-os/deploy/.env com permissão 600, nunca em controle de versão.

Exemplos de Uso

Exemplos utilizando curl na linha de comando:

Retain (assíncrono)

curl -X POST https://memory.bonnano.com.br/mcp/context-os/ \
  -H "Authorization: Bearer $MEMORY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "retain", "arguments": {"content": "Decisão: usar PostgreSQL externo em produção"}}, "id": 1}'

Recall

curl -X POST https://memory.bonnano.com.br/mcp/context-os/ \
  -H "Authorization: Bearer $MEMORY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "recall", "arguments": {"query": "decisões sobre banco de dados"}}, "id": 2}'

Certifique-se de que a variável MEMORY_API_TOKEN está definida no seu shell antes de executar os comandos: export MEMORY_API_TOKEN="seu-token-aqui"