# 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. - Canonical: https://docs.xmemo.dev/docs/mcp/claude - Locale: en-US - Content-Locale: en-US - Canonical-Content-Digest: de1a3fce819ac5cc3e4ef555fb6ba57c0ae2af9af5e91367ad4efac64a274ea3 - Edition-Digest: b3985db12c0ec2426916ddbb1d399e34fbf48b4f3f1066cb228e38a55a3815a9 - Source-Revision: sha256:ef049dd959bada93a714e560eece53ae72cd3ce2d2ed84bbab43191b9ae93474 ## 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. ```text 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. ```text ### XMemo Memory Results: 1. Reference: | Location: > ``` ## 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.