# MCP overview

Cross-agent durable memory configuration for Claude, ChatGPT, Codex, GitHub Copilot, and OpenClaw via hosted MCP endpoints.

- Canonical: https://docs.xmemo.dev/docs/mcp/overview
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 95c2cc6763387aa6fe7f2b496f0154a132a5c211018329027bf0f9c41040a44b
- Edition-Digest: 0683f1d7896c9e6bdb0b56cb0aeb51e2698a705fdcb99983d3babf3fdd30f6ae
- Source-Revision: sha256:8a7f17b8385ff22f0e8248ad6c7836bd2a740d9b56274c79839a48cac9707807

## Connect XMemo to your AI environment

XMemo provides durable project memory across Claude, ChatGPT, Codex, GitHub Copilot, OpenClaw, and open AI agent runtimes. Every client talks to the same hosted Streamable HTTP endpoint, whether through browser OAuth or direct bearer tokens.

- Claude (Axis A: Config supported; Evidence required for current client proof · Axis B: Manual MCP Configuration): Eight professional memory workflows, lifecycle checkpoints, and cross-agent continuity for Claude Code and Cowork.
- ChatGPT (Axis A: Hosted beta pilot; Evidence required for any refreshed external claim · Axis B: Manual MCP Configuration; Marketplace pending): 20 focused tools, eight professional memory workflows, and interactive workspaces (TODO Board, Ledger, Project Workspace).
- Codex (Axis A: Config supported; Evidence required · Axis B: Manual MCP Configuration): Skill-guided project memory and MCP authorization.
- OpenClaw (Axis A: Released; Pilot tested · Axis B: Official Marketplace, Native Integration): Recall-first Skill guidance plus a native OpenClaw memory plugin on ClawHub.
- GitHub Copilot & VS Code (Axis A: Config supported; Evidence required for current client proof · Axis B: Manual MCP Configuration): MCP integration for IDE and CLI agents.
- Gemini CLI (Axis A: Config supported; Evidence required for current client proof · Axis B: Manual MCP Configuration): OAuth-first configuration without placing bearer credentials in settings.json.

## Two orthogonal delivery axes: availability and distribution mode

Client integrations are classified along two independent axes: Axis A represents empirical readiness and availability status (Released, Pilot / Entitled, or Planned), while Axis B defines the integration and distribution mode (Official Marketplace, Community Directory, Native Integration, or Manual MCP Configuration). The delivery channel does not determine availability, and roadmap features remain strictly distinguished from production runtimes.

- Axis A (Availability / Evidence Status): Released (fully operational in production), Pilot / Entitled (hosted beta pilot or commercial entitlement required), Planned (roadmap items requiring explicit forward-looking disclosure).
- Axis B (Integration / Distribution Mode): Official Marketplace (vendor-reviewed listings such as ClawHub official skill), Community Directory (third-party index listings), Native Integration (embedded runtime support), Manual MCP Configuration (user-configured JSON snippets).

## One endpoint, two authentication modes

Every client talks to the same hosted Streamable HTTP endpoint. What differs is how the client proves who it is.

- OAuth clients: ChatGPT, VS Code / GitHub Copilot, Cursor, Gemini CLI.
- Direct token clients: Claude Code, Codex, Copilot CLI, headless runners.
- Transport is streamable-http in both cases.

## OAuth client configuration

The hosted URL is the entire configuration; the grant supplies the scopes.

```json
{
  "servers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp"
    }
  }
}
```

## Direct token configuration

Headless runners that cannot complete OAuth read the token from the environment instead.

```json
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "transport": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "${XMEMO_AGENT_ID}",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```

## Let a runner configure itself

An autonomous runner can fetch its own preset instead of asking a human to type identity values.

```bash
curl -s https://xmemo.dev/api/v1/mcp/config/autonomous-agent
```

## VS Code / GitHub Copilot

OAuth client: keep only the hosted server URL in mcp.json; first tool call opens browser OAuth, so no XMEMO_KEY or Authorization header belongs in this file.

```
{
  "servers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp"
    }
  }
}
```

## Cursor

Direct client: configure in ~/.cursor/mcp.json with XMEMO_KEY in the environment. Run npx @xmemo/client mcp add cursor to install automatically.

```
{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "cursor",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```

## Codex

Direct client: Codex reads XMEMO_KEY through bearer_token_env_var and sends non-secret identity headers. Run npx @xmemo/client mcp add codex --write to generate the stable XMEMO_AGENT_INSTANCE_ID automatically.

```
[mcp_servers.XMemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"

[mcp_servers.XMemo.http_headers]
X-Memory-OS-Agent-ID = "codex"
X-Memory-OS-Agent-Instance-ID = "${XMEMO_AGENT_INSTANCE_ID}"

```

## Gemini CLI

OAuth client: merge this XMemo block into settings.json, set one stable XMEMO_AGENT_INSTANCE_ID for local attribution, then restart Gemini CLI and complete MCP OAuth. Do not add Authorization or XMEMO_KEY to this snippet.

```
{
  "mcpServers": {
    "XMemo": {
      "httpUrl": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "gemini-cli",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```

## Claude Desktop

Stdio bridge: Claude Desktop uses mcp-remote to connect to hosted streamable-http with XMEMO_KEY from the environment. Run npx @xmemo/client mcp add claude-desktop to configure automatically.

```
{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:claude-desktop",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_KEY": "${env:XMEMO_KEY}",
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```

## Devin Desktop (formerly Windsurf)

Direct client: configure manually in ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows) with XMEMO_KEY in the environment. Note: npx @xmemo/client mcp add windsurf currently writes the pre-rename location ~/.codeium/windsurf/mcp_config.json (useful only for pre-rename installs), so Devin Desktop users should configure manually or move the file.

```
{
  "mcpServers": {
    "XMemo": {
      "serverUrl": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "windsurf",
        "X-Memory-OS-Agent-Instance-ID": "${env:XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```

## Kiro

OAuth client: configure in ~/.kiro/settings/mcp.json. Supports OAuth with memory:read and knowledge:read scopes. Run npx @xmemo/client mcp add kiro to install automatically.

```
{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "kiro",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      },
      "oauth": {
        "oauthScopes": [
          "memory:read",
          "knowledge:read"
        ]
      }
    }
  }
}
```

## OpenClaw

Direct client: configure in ~/.openclaw/openclaw.json with XMEMO_KEY in the environment. Run npx @xmemo/client mcp add openclaw to install automatically.

```
{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "openclaw",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```

## Copilot CLI

Direct client: set XMEMO_KEY in the user environment or a supported secret reference, then replace the stable instance placeholder before applying the reviewed config.

```
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "tools": ["*"],
      "timeout": 30000,
      "headers": {
        "Authorization": "Bearer <replace-with-XMEMO_KEY-or-supported-secret-reference>",
        "X-Memory-OS-Agent-ID": "copilot-cli",
        "X-Memory-OS-Agent-Instance-ID": "<stable-local-copilot-cli-instance-id>"
      }
    }
  }
}
```

## ChatGPT / OpenAI Apps SDK

OAuth marketplace lane: configure the hosted MCP URL and OAuth metadata in the OpenAI app dashboard; never paste XMEMO_KEY or Bearer tokens into the listing.

```
{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "transport": "streamable-http",
      "auth": {
        "type": "oauth2",
        "resource": "https://xmemo.dev/mcp",
        "scopes": ["memory:read", "memory:write"]
      }
    }
  }
}
```

## Autonomous agent

OAuth-first self-config preset: fetch /api/v1/mcp/config/autonomous-agent, use auth_modes.oauth when the runner supports OAuth + custom headers, fall back to auth_modes.xmemo_key for headless runners, and never ask the human for agent_id or instance_id.

```
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "transport": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "autonomous-agent",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      },
      "auth": {
        "type": "oauth2",
        "flow": "authorization_code",
        "pkce_required": true,
        "resource": "https://xmemo.dev/mcp",
        "scopes": ["memory:read", "memory:write"]
      },
      "fallback": {
        "use_when": "headless runner cannot complete OAuth sign-in or persist OAuth tokens",
        "authorization_header": "Bearer ${XMEMO_KEY}"
      }
    }
  }
}
```

## Other

Generic direct client: the client must support streamable-http and Authorization headers; set XMEMO_AGENT_ID and a stable XMEMO_AGENT_INSTANCE_ID only for non-secret attribution.

```
{
  "mcpServers": {
    "XMemo": {
      "transport": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "${XMEMO_AGENT_ID}",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```