Claude Code

A CLI claude mcp add do Claude Code faz a edição da configuração por você e mantém o registro com escopo por projeto ou por usuário. O OAuth roda no seu navegador na primeira vez que você chama uma ferramenta do Engram. Para o contexto do protocolo, veja MCP.

Pré-requisitos

Antes de começar, confirme:

• Você tem uma conta do Engram em app.engram.page.
• Pelo menos um cofre está sincronizado. Abra o plugin do Obsidian ou o app web e confirme que as notas foram sincronizadas no último dia.
• Você consegue entrar pelo navegador. O fluxo de autenticação do MCP abre uma janela do navegador.
• Se você pretende usar uma chave de API em vez do OAuth: chaves de API exigem o Pro. O login por OAuth funciona em todos os planos, inclusive o Free, e é o caminho recomendado. Free e Starter não podem criar nem usar chaves de API.

Endpoint

https://mcp.engram.page

Configuração

1. Registre o Engram na CLI do Claude Code.

claude mcp add --transport http --scope user engram https://mcp.engram.page

--scope user deixa o Engram disponível em todos os projetos. Use --scope project para limitar o Engram ao .mcp.json do repositório atual.

Prefere editar à mão? Adicione o bloco abaixo ao ~/.claude.json (escopo de usuário) ou ao .mcp.json na raiz do projeto:

{
  "mcpServers": {
    "engram": {
      "url": "https://mcp.engram.page"
    }
  }
}

2. Recarregue. Saia da sessão atual do Claude Code e execute claude de novo. Rode claude mcp list para confirmar que o Engram está registrado. Ele deve aparecer com o status △ needs authentication.

Primeira autenticação

O Claude Code não pede o OAuth automaticamente. Em uma sessão nova, execute /mcp, selecione engram e escolha Authenticate. Seu navegador abre para você entrar no Engram e aprovar a conexão. O Claude Code guarda o token e o reutiliza dali em diante. A concessão é o escopo mcp completo. Escopos granulares por ação estão no roteiro.

Diga ao Claude como usá-lo

Acrescente o trecho abaixo ao ~/.claude/CLAUDE.md, o arquivo de instruções no nível do usuário do Claude Code. Ele vale para todos os projetos. Ajustes por repositório vão em um CLAUDE.md no nível do projeto, na raiz do repositório.

Engram holds my personal notes — treat it as your long-term memory of me. Search it when a question depends on context I might have shared before. Before saving or updating a note, ask first.

Experimente

Com o registro feito e autenticado, pergunte ao Claude:

• Pesquise no meu cofre as notas sobre o processo de entrevistas de engenharia e resuma as três principais.
• Encontre tudo o que escrevi sobre embeddings no último mês.

O Claude chama a ferramenta search do Engram (ou get_note, write_note etc.), traz os resultados e responde no contexto. Se a ferramenta disparar, está tudo certo.

Chave de API em vez de OAuth

Para máquinas headless, CI ou um cofre compartilhado, dispense o OAuth e fixe a conexão em uma chave de API do Engram. Gere uma em app.engram.page/settings/api-keys e envie-a como cabeçalho Bearer.

A versão rápida grava a chave direto no arquivo de configuração:

claude mcp add --transport http --scope user engram https://mcp.engram.page \
  --header "Authorization: Bearer engram_YOUR_KEY_HERE"

Isso é aceitável para --scope user (o ~/.claude.json fica na sua máquina). Não é aceitável para --scope project, porque o .mcp.json foi feito para ir ao repositório. Carregue a chave pelo ambiente.

Carregue a chave de uma variável de ambiente

O Claude Code expande ${VAR} e ${VAR:-default} ao ler o .mcp.json. Em servidores HTTP, a expansão cobre os campos url e headers, que é exatamente onde fica uma chave de API. Faça commit disto:

{
  "mcpServers": {
    "engram": {
      "type": "http",
      "url": "https://mcp.engram.page",
      "headers": {
        "Authorization": "Bearer ${ENGRAM_API_KEY}"
      }
    }
  }
}

Só o nome da variável vai para o repositório. Cada colaborador fornece a própria chave, e o Engram vincula cada uma à sua própria conta, então um .mcp.json compartilhado nunca implica um cofre compartilhado.

O Claude Code lê o ambiente com o qual foi iniciado, então exporte a chave antes de iniciar o claude:

export ENGRAM_API_KEY="engram_YOUR_KEY_HERE"

Para uma chave por repositório, use o direnv e guarde o valor em um .envrc ignorado pelo git:

export ENGRAM_API_KEY="engram_YOUR_KEY_HERE"

Execute direnv allow uma vez e depois inicie o claude a partir desse diretório.

Cuidado

Se a variável não estiver definida, a configuração ainda assim é carregada e o Claude Code envia a string literal Bearer ${ENGRAM_API_KEY}, que o Engram rejeita com um 401. O claude mcp list sinaliza isso:

[Warning] [engram] mcpServers.engram: Missing environment variables: ENGRAM_API_KEY

Procure essa linha primeiro quando uma configuração com chave não conectar.

Duas coisas mudam quando há uma chave em uso. Nenhum navegador abre na primeira conexão, e o /mcp deixa de oferecer Authenticate: definir um cabeçalho Authorization desativa por completo o fallback para OAuth. Veja Configuração do MCP → Autenticação por chave de API para saber o que uma chave cobre e como rotacioná-la.

Solução de problemas (específico do Claude Code)

• O claude mcp list não mostra o engram. O comando rodou em um escopo diferente do esperado. Procure a entrada em ~/.claude.json (usuário) e em .mcp.json (projeto) e execute claude mcp add de novo com a flag --scope correta.
• O /mcp não lista o engram no seletor. Você não saiu da CLI nem a reiniciou depois do claude mcp add. Reinicie o claude.
• A opção Authenticate não faz nada, ou o navegador nunca abre. Uma sessão headless ou remota não consegue abrir um navegador. Rode o Claude Code em uma máquina com navegador desktop, ou use uma chave de API.

Para falhas comuns a todos os clientes, veja Solução de problemas.

Revogação

Para desconectar Claude Code do Engram:

1. Em Claude Code, encontre a entrada do conector ou do servidor MCP e remova-a.
2. No Engram, abra sua conta → API Keys & Sessions e revogue a sessão correspondente.
3. O token OAuth é invalidado no servidor. Claude Code precisará se autenticar de novo para reconectar.

Você também pode remover o registro localmente com claude mcp remove engram. Isso apaga a entrada de configuração, mas mantém o token no servidor ativo até que você o revogue no Engram.

Próximos passos

MCPVisão geral do protocolo.

EscoposO que a concessão cobre.

Todas as integraçõesEscolha outro cliente.