连接连接Claude (claude.ai)

MCP Client

Claude (claude.ai)

将 claude.ai 上的 Claude 作为自定义连接器连接到托管的 Streamable HTTP MCP 端点，使用 OAuth 以及 memory:read 和 memory:write 权限范围。

前置条件

使用支持自定义连接器的 Claude，以及有效的 XMemo 账户。连接信息：

  • 界面：网页版 Claude (claude.ai)，通过自定义连接器连接。
  • 连接 URL：https://xmemo.dev/mcp。
  • 传输方式：Streamable HTTP (streamable-http)。
  • 认证模式：使用 PKCE 和动态客户端注册 (Dynamic Client Registration) 的 OAuth 2.0 授权码流程。
  • 权限范围：memory:read 和 memory:write。
  • 账户：https://xmemo.dev 上的有效 XMemo 账户。

将 XMemo 添加为自定义连接器

在 Claude 中添加托管的 MCP 服务器。连接 URL 是唯一的服务器设置：

  • 1. 在 Claude 中打开 Customize > Connectors，然后选择 Add custom connector。直达链接：https://claude.ai/customize/connectors?modal=add-custom-connector。
  • 2. 名称：XMemo。
  • 3. 远程 MCP 服务器 URL：https://xmemo.dev/mcp。
  • 4. 添加连接器，然后点击 Connect 开始 OAuth。

通过 OAuth 批准访问

Claude 通过动态客户端注册将自身注册为 OAuth 客户端，并在浏览器中打开 XMemo 授权页面。登录后，在同意页面批准 memory:read 和 memory:write。Claude 从此 OAuth 授权中获得凭据。

不要添加 bearer token

自定义连接器不需要 API key。不要将 XMemo API key、XMEMO_KEY 或 bearer token 填入连接器；OAuth 授权会提供凭据及其权限范围。

在对话中启用 XMemo

返回 Claude，并为当前对话启用 XMemo。之后 Claude 会发现 XMemo 工具及其标题和安全注解。

通过真实的 recall 调用进行测试

第一次调用请保持只读。这是一次真实的 recall 调用，而非健康检查占位符，并且不会写入记忆。

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

预期响应（字面形态）

调用成功时会返回下方的公开排序文本形态；其中的引用和内容是已授权记忆空间中的真实值。

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

Claude 中可用的工具

在 claude-public 配置文件中，Claude 可以看到 27 个工具。下面按安全注解分组：读取工具从不更改数据，写入工具新增、完成或恢复记录，破坏性工具可能覆盖、更改或删除现有记录。拥有专门参考页面的工具附有链接，其余工具仅在本页说明。

读取工具

只读且幂等；这些工具不会更改已存储的数据：

  • get_mcp_identity (Check XMemo connection)：返回已认证的连接器身份以及已授予的记忆权限范围。
  • [search_memory](/docs/tools/search) (Search XMemo memories)：搜索可见的限定范围记忆或团队记忆记录。
  • [recall](/docs/tools/recall) (Recall XMemo memory)：检索最相关的可见记忆。
  • [recall_context](/docs/tools/recall-context) (Build XMemo context)：根据可见记忆构建有边界的上下文包。
  • memory_overview (Show XMemo memory overview)：汇总可见记忆和近期活动。
  • memory_stats (Show XMemo memory statistics)：返回可见记忆的汇总统计。
  • memory_activity (Show XMemo memory activity)：显示你自己记忆变更的安全时间线，不暴露原始审计日志。
  • analyze_memory_text (Analyze XMemo memory text)：统计某个词或精确短语在可见记忆中出现的次数。
  • explain_memory (Explain XMemo memory)：解释某条可见记忆为何存在或为何与查询匹配。
  • list_memory_todos (List XMemo memory TODOs)：列出基于记忆的 TODO 和行动项；Claude 通过它读取 TODO。
  • list_ledger_transactions (List XMemo Ledger transactions)：列出可见的 Ledger 记录。
  • get_monthly_ledger_summary (Summarize XMemo Ledger by month)：按月汇总可见的 Ledger 记录。
  • read_memory (Read Memory)：按 recall 或搜索返回的引用，读取一条精确记忆或一个已授权 Document 的有界页面。
  • get_project_context (Get project context)：读取你拥有或可访问的某个项目的已授权上下文。

写入工具

这些工具新增、完成或恢复记录，未被标记为破坏性：

  • add_expense (Record an XMemo Ledger transaction)：创建一条结构化 Ledger 记录。
  • complete_memory_todo (Complete XMemo memory TODO)：将一个现有的基于记忆的 TODO 或行动项标记为已完成。
  • create_memory_todo (Create XMemo memory TODO)：创建一个基于记忆的 TODO 或行动项。
  • [remember](/docs/tools/remember) (Remember in XMemo)：创建一条限定范围的记忆，或对其去重。
  • restore_memory (Restore XMemo memory)：恢复被 forget 以默认软删除模式移除的记录。
  • record_event (Record a milestone)：追加一条里程碑或交接事件；它从不编辑或删除现有记录。
  • create_pending_decision (Save a pending decision)：保存一项未决决策及其上下文和选项，供之后审阅。
  • resolve_decision (Resolve a pending decision)：为一项确切的待定决策记录所选结果并将其关闭，同时保留其历史。

破坏性工具

这些工具被标记为破坏性，因为它们可能覆盖、更改或删除现有记录：

  • [forget](/docs/tools/forget) (Forget XMemo memory, TODO, or Ledger transaction)：删除一条选定的记忆、TODO 或 Ledger 记录；参见下方的“删除与恢复”。
  • update_memory (Update XMemo memory)：按精确引用覆盖一条选定记忆的字段。
  • update_state (Save working state)：保存或替换一个命名的工作状态检查点，以便之后的对话可以继续。
  • [todo](/docs/tools/todos) (Manage XMemo TODOs)：创建、更新或完成你自己的 TODO；参见下方的“Claude 中的 TODO”。
  • project (Manage XMemo project)：创建项目，或更改某个已授权项目的记忆、决策、文档和对话链接或设置。

删除与恢复

除非你明确要求永久删除，否则通过 forget 进行的删除都可以恢复：

  • 默认：forget 执行可恢复的软删除。
  • 撤销：restore_memory 恢复被软删除的记录。
  • 永久：使用 mode='hard' 的 forget 是永久且不可恢复的。它需要你的明确确认，且被硬删除的记录无法恢复。

Claude 中的 TODO

在 Claude 中，todo 工具只用于创建、更新或完成 TODO。Claude 使用 list_memory_todos 读取 TODO。todo 参考页面描述了完整的调度器；在 Claude 中，仅将其用于这三种操作。

Claude Desktop

在 Claude Desktop 中，请从相同的自定义连接器和 OAuth 流程开始。使用 API key 的本地配置仍是备选方案：

  • 推荐：将 XMemo 添加为指向 https://xmemo.dev/mcp 的自定义连接器并完成 OAuth。无需 API key。
  • 备选：在 claude_desktop_config.json 中配置第一方 xmemo-mcp stdio 代理或 mcp-remote，并使用 XMemo API key。stdio 代理配置请参见 [MCP 概览](/docs/mcp/overview)。

Claude Code

Claude Code 使用单独的设置。独立 Skill 和直接 MCP 配置请参见 [Claude Code](/docs/mcp/claude-code)。

常见错误

OAuth 失败对应真实的令牌端点响应：

  • invalid_grant — 授权码无效、已过期或已被使用：在 Claude 中重新连接 XMemo 并再次授权。
  • invalid_target — OAuth 资源与此 MCP 服务器不匹配：移除连接器，并使用 https://xmemo.dev/mcp 重新添加。
  • 403 insufficient_scope — 授权不包含 memory:read 或 memory:write：批准这两个权限范围后重新连接。

更新与移除

Claude 连接器的维护步骤：

  • 重新连接：如果 Claude 显示 XMemo 的授权或重新连接提示，请重新连接该连接器并再次完成 OAuth。
  • 移除：在 Claude 的连接器设置中移除 XMemo 自定义连接器。

来源: 客户端能力矩阵