ConnectConnectClaude (claude.ai)

MCP Client

Claude (claude.ai)

Connect Claude on claude.ai as a custom connector to the hosted Streamable HTTP MCP endpoint with OAuth and memory:read and memory:write scopes.

Prerequisite

Use Claude with custom connector support and a valid XMemo account. Connection details:

  • Interface: Claude on the web (claude.ai), connected through a custom connector.
  • Connection URL: https://xmemo.dev/mcp.
  • Transport: Streamable HTTP (streamable-http).
  • Auth mode: OAuth 2.0 authorization code with PKCE and Dynamic Client Registration.
  • Scopes: memory:read and memory:write.
  • Account: Valid XMemo account at https://xmemo.dev.

Add XMemo as a custom connector

Add the hosted MCP server in Claude. The connection URL is the only server setting:

  • 1. In Claude, open Customize > Connectors and choose Add custom connector. Direct link: https://claude.ai/customize/connectors?modal=add-custom-connector.
  • 2. Name: XMemo.
  • 3. Remote MCP server URL: https://xmemo.dev/mcp.
  • 4. Add the connector, then click Connect to start OAuth.

Approve access with OAuth

Claude registers itself as an OAuth client through Dynamic Client Registration and opens the XMemo authorization page in your browser. Sign in and approve memory:read and memory:write at consent. Claude receives its credential from this OAuth grant.

Do not add a bearer token

The custom connector needs no API key. Do not put an XMemo API key, XMEMO_KEY, or a bearer token into the connector; the OAuth grant supplies the credential and its scopes.

Enable XMemo in a conversation

Return to Claude and enable XMemo for the conversation. Claude then discovers the XMemo tools with their titles and safety annotations.

Test with a real recall call

Make the first call read-only. This is an actual recall invocation, not a health-check placeholder, and it does not write memory.

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

Expected response (literal shape)

A successful call returns the public ranked text shape below; the reference and content are real values from the authorized memory space.

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

Tools available in Claude

On the claude-public profile Claude sees 27 tools. They are grouped below by safety annotation: read tools never change data, write tools add, complete, or restore records, and destructive tools can overwrite, change, or delete existing records. Tools that have a dedicated reference page are linked; the others are described only on this page.

Read tools

Read-only and idempotent; these tools do not change stored data:

  • get_mcp_identity (Check XMemo connection): returns the authenticated connector identity and granted memory scopes.
  • [search_memory](/docs/tools/search) (Search XMemo memories): searches visible scoped or team memory records.
  • [recall](/docs/tools/recall) (Recall XMemo memory): retrieves the most relevant visible memories.
  • [recall_context](/docs/tools/recall-context) (Build XMemo context): builds a bounded context pack from visible memories.
  • memory_overview (Show XMemo memory overview): summarizes visible memories and recent activity.
  • memory_stats (Show XMemo memory statistics): returns aggregate statistics over visible memories.
  • memory_activity (Show XMemo memory activity): shows a safe timeline of your own memory changes without exposing raw audit logs.
  • analyze_memory_text (Analyze XMemo memory text): counts a word or exact phrase across visible memories.
  • explain_memory (Explain XMemo memory): explains why a visible memory exists or matched a query.
  • list_memory_todos (List XMemo memory TODOs): lists memory-backed TODOs and action items; this is how Claude reads TODOs.
  • list_ledger_transactions (List XMemo Ledger transactions): lists visible Ledger records.
  • get_monthly_ledger_summary (Summarize XMemo Ledger by month): summarizes visible Ledger records by month.
  • read_memory (Read Memory): reads a bounded page of one exact memory, or of an authorized Document by its document reference, as returned by recall or search.
  • get_project_context (Get project context): reads the authorized context of one project you own or can access.

Write tools

These tools add, complete, or restore records and are not marked destructive:

  • add_expense (Record an XMemo Ledger transaction): creates one structured Ledger record.
  • complete_memory_todo (Complete XMemo memory TODO): marks an existing memory-backed TODO or action item as completed.
  • create_memory_todo (Create XMemo memory TODO): creates a memory-backed TODO or action item.
  • [remember](/docs/tools/remember) (Remember in XMemo): creates or deduplicates a scoped memory.
  • restore_memory (Restore XMemo memory): restores a record removed by forget in its default soft-delete mode.
  • record_event (Record a milestone): appends one milestone or handoff event; it never edits or deletes existing records.
  • create_pending_decision (Save a pending decision): saves one unresolved decision with its context and options for later review.
  • resolve_decision (Resolve a pending decision): records the chosen outcome for an exact pending decision and closes it while keeping its history.

Destructive tools

These tools are marked destructive because they can overwrite, change, or delete existing records:

  • [forget](/docs/tools/forget) (Forget XMemo memory, TODO, or Ledger transaction): deletes one selected memory, TODO, or Ledger record; see Deletion and recovery below.
  • update_memory (Update XMemo memory): overwrites fields of one selected memory by exact reference.
  • update_state (Save working state): saves or replaces one named working-state checkpoint so a later conversation can resume it.
  • [todo](/docs/tools/todos) (Manage XMemo TODOs): creates, updates, or completes your own TODOs; see TODOs in Claude below.
  • project (Manage XMemo project): creates a project, or changes an authorized project's memories, decisions, document and conversation links, or settings.

Deletion and recovery

Deletion through forget is recoverable unless you explicitly ask for permanent deletion:

  • Default: forget performs a recoverable soft deletion.
  • Undo: restore_memory restores a record removed by a soft delete.
  • Permanent: forget with mode='hard' is permanent and unrecoverable. It requires your explicit confirmation, and a hard-deleted record cannot be restored.

TODOs in Claude

In Claude, the todo tool only creates, updates, or completes TODOs. Claude reads TODOs with list_memory_todos. The todo reference page describes the full dispatcher; in Claude, use it only for these three actions.

Claude Desktop

Start Claude Desktop with the same custom connector and OAuth flow. Local configuration with an API key remains an alternative:

  • Recommended: add XMemo as a custom connector with https://xmemo.dev/mcp and complete OAuth. No API key is needed.
  • Alternative: configure the first-party xmemo-mcp stdio proxy or mcp-remote in claude_desktop_config.json with an XMemo API key. See the [MCP overview](/docs/mcp/overview) for the stdio proxy configuration.

Claude Code

Claude Code uses a separate setup. See [Claude Code](/docs/mcp/claude-code) for the standalone Skill and direct MCP configuration.

Common Errors

OAuth failures map to the real token endpoint responses:

  • invalid_grant — The authorization code is invalid, expired, or already used: reconnect XMemo in Claude and authorize again.
  • invalid_target — The OAuth resource does not match this MCP server: remove the connector and add it again with https://xmemo.dev/mcp.
  • 403 insufficient_scope — The grant does not include memory:read or memory:write: approve both scopes and reconnect.

Update and removal

Maintenance procedures for the Claude connector:

  • Reconnect: if Claude shows an authorization or reconnect message for XMemo, reconnect the connector and complete OAuth again.
  • Removal: remove the XMemo custom connector from Claude's connector settings.

Source: Client capability matrix