ConectarConectarClaude (claude.ai)

MCP Client

Claude (claude.ai)

Conecte o Claude no claude.ai como conector personalizado ao endpoint MCP hospedado de Streamable HTTP com OAuth e os escopos memory:read e memory:write.

Pré-requisito

Use o Claude com suporte a conectores personalizados e uma conta válida do XMemo. Detalhes da conexão:

  • Interface: Claude na web (claude.ai), conectado por meio de um conector personalizado.
  • URL de conexão: https://xmemo.dev/mcp.
  • Transporte: Streamable HTTP (streamable-http).
  • Modo de autenticação: código de autorização OAuth 2.0 com PKCE e Dynamic Client Registration (registro dinâmico de clientes).
  • Escopos: memory:read e memory:write.
  • Conta: conta válida do XMemo em https://xmemo.dev.

Adicionar o XMemo como conector personalizado

Adicione o servidor MCP hospedado no Claude. A URL de conexão é a única configuração do servidor:

  • 1. No Claude, abra Customize > Connectors e escolha Add custom connector. Link direto: https://claude.ai/customize/connectors?modal=add-custom-connector.
  • 2. Nome: XMemo.
  • 3. URL do servidor MCP remoto: https://xmemo.dev/mcp.
  • 4. Adicione o conector e clique em Connect para iniciar o OAuth.

Aprovar o acesso com OAuth

O Claude se registra como cliente OAuth por meio do Dynamic Client Registration e abre a página de autorização do XMemo no seu navegador. Entre e aprove memory:read e memory:write no consentimento. O Claude recebe a credencial a partir dessa concessão OAuth.

Não adicione um token bearer

O conector personalizado não precisa de API key. Não coloque uma API key do XMemo, XMEMO_KEY ou um token bearer no conector; a concessão OAuth fornece a credencial e seus escopos.

Ativar o XMemo em uma conversa

Volte ao Claude e ative o XMemo para a conversa. Em seguida, o Claude descobre as ferramentas do XMemo com seus títulos e anotações de segurança.

Testar com uma chamada real de recall

Faça com que a primeira chamada seja somente leitura. É uma invocação real de recall, não um marcador de verificação de integridade, e não grava na memória.

recall({ query: "connection check", limit: 1 })

Resposta esperada (formato literal)

Uma chamada bem-sucedida retorna o formato público de texto classificado abaixo; a referência e o conteúdo são valores reais do espaço de memória autorizado.

### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>

Ferramentas disponíveis no Claude

No perfil claude-public, o Claude vê 27 ferramentas. Elas estão agrupadas abaixo por anotação de segurança: as ferramentas de leitura nunca alteram dados, as de escrita adicionam, concluem ou restauram registros e as destrutivas podem sobrescrever, alterar ou excluir registros existentes. As ferramentas com página de referência própria têm link; as demais são descritas apenas nesta página.

Ferramentas de leitura

Somente leitura e idempotentes; estas ferramentas não alteram dados armazenados:

  • get_mcp_identity (Check XMemo connection): retorna a identidade autenticada do conector e os escopos de memória concedidos.
  • [search_memory](/docs/tools/search) (Search XMemo memories): pesquisa registros visíveis de memória com escopo ou de equipe.
  • [recall](/docs/tools/recall) (Recall XMemo memory): recupera as memórias visíveis mais relevantes.
  • [recall_context](/docs/tools/recall-context) (Build XMemo context): monta um pacote de contexto delimitado a partir de memórias visíveis.
  • memory_overview (Show XMemo memory overview): resume as memórias visíveis e a atividade recente.
  • memory_stats (Show XMemo memory statistics): retorna estatísticas agregadas sobre as memórias visíveis.
  • memory_activity (Show XMemo memory activity): mostra uma linha do tempo segura das alterações na sua própria memória, sem expor logs de auditoria brutos.
  • analyze_memory_text (Analyze XMemo memory text): conta uma palavra ou frase exata nas memórias visíveis.
  • explain_memory (Explain XMemo memory): explica por que uma memória visível existe ou correspondeu a uma consulta.
  • list_memory_todos (List XMemo memory TODOs): lista TODOs e itens de ação baseados em memória; é assim que o Claude lê TODOs.
  • list_ledger_transactions (List XMemo Ledger transactions): lista os registros visíveis do Ledger.
  • get_monthly_ledger_summary (Summarize XMemo Ledger by month): resume por mês os registros visíveis do Ledger.
  • read_memory (Read Memory): lê uma página delimitada de uma memória exata, ou de um Document autorizado pela referência do documento, conforme retornada por recall ou pela pesquisa.
  • get_project_context (Get project context): lê o contexto autorizado de um projeto que você possui ou ao qual tem acesso.

Ferramentas de escrita

Estas ferramentas adicionam, concluem ou restauram registros e não são marcadas como destrutivas:

  • add_expense (Record an XMemo Ledger transaction): cria um registro estruturado do Ledger.
  • complete_memory_todo (Complete XMemo memory TODO): marca como concluído um TODO ou item de ação existente baseado em memória.
  • create_memory_todo (Create XMemo memory TODO): cria um TODO ou item de ação baseado em memória.
  • [remember](/docs/tools/remember) (Remember in XMemo): cria ou desduplica uma memória com escopo.
  • restore_memory (Restore XMemo memory): restaura um registro removido pelo forget no modo padrão de exclusão reversível.
  • record_event (Record a milestone): acrescenta um evento de marco ou de passagem de trabalho; nunca edita nem exclui registros existentes.
  • create_pending_decision (Save a pending decision): salva uma decisão não resolvida com seu contexto e opções para revisão posterior.
  • resolve_decision (Resolve a pending decision): registra o resultado escolhido para uma decisão pendente exata e a encerra, mantendo seu histórico.

Ferramentas destrutivas

Estas ferramentas são marcadas como destrutivas porque podem sobrescrever, alterar ou excluir registros existentes:

  • [forget](/docs/tools/forget) (Forget XMemo memory, TODO, or Ledger transaction): exclui uma memória, um TODO ou um registro do Ledger selecionado; consulte Exclusão e recuperação abaixo.
  • update_memory (Update XMemo memory): sobrescreve campos de uma memória selecionada pela referência exata.
  • update_state (Save working state): salva ou substitui um checkpoint nomeado de estado de trabalho para que uma conversa posterior possa retomá-lo.
  • [todo](/docs/tools/todos) (Manage XMemo TODOs): cria, atualiza ou conclui seus próprios TODOs; consulte TODOs no Claude abaixo.
  • project (Manage XMemo project): cria um projeto ou altera as memórias, decisões, links de documentos e conversas, ou as configurações de um projeto autorizado.

Exclusão e recuperação

A exclusão pelo forget é recuperável, a menos que você peça explicitamente uma exclusão permanente:

  • Padrão: o forget executa uma exclusão reversível (soft delete).
  • Desfazer: o restore_memory restaura um registro removido por exclusão reversível.
  • Permanente: o forget com mode='hard' é permanente e irrecuperável. Exige sua confirmação explícita, e um registro excluído permanentemente não pode ser restaurado.

TODOs no Claude

No Claude, a ferramenta todo apenas cria, atualiza ou conclui TODOs. O Claude lê TODOs com list_memory_todos. A página de referência do todo descreve o despachante completo; no Claude, use-a apenas para essas três ações.

Claude Desktop

Comece no Claude Desktop com o mesmo conector personalizado e fluxo OAuth. A configuração local com uma API key continua sendo uma alternativa:

  • Recomendado: adicione o XMemo como conector personalizado com https://xmemo.dev/mcp e conclua o OAuth. Nenhuma API key é necessária.
  • Alternativa: configure o proxy stdio oficial xmemo-mcp ou o mcp-remote em claude_desktop_config.json com uma API key do XMemo. Consulte a [visão geral do MCP](/docs/mcp/overview) para a configuração do proxy stdio.

Claude Code

O Claude Code usa uma configuração separada. Consulte [Claude Code](/docs/mcp/claude-code) para o Skill independente e a configuração direta de MCP.

Erros comuns

As falhas de OAuth correspondem às respostas reais do endpoint de token:

  • invalid_grant — O código de autorização é inválido, expirou ou já foi usado: reconecte o XMemo no Claude e autorize novamente.
  • invalid_target — O recurso OAuth não corresponde a este servidor MCP: remova o conector e adicione-o novamente com https://xmemo.dev/mcp.
  • 403 insufficient_scope — A concessão não inclui memory:read ou memory:write: aprove os dois escopos e reconecte.

Atualização e remoção

Procedimentos de manutenção do conector do Claude:

  • Reconectar: se o Claude mostrar uma mensagem de autorização ou reconexão para o XMemo, reconecte o conector e conclua o OAuth novamente.
  • Remoção: remova o conector personalizado do XMemo nas configurações de conectores do Claude.

Origem: Matriz de capacidades do cliente