# Claude MCP (Manual)

> Manually connect xmemory to Claude through MCP.

Canonical page: https://xmemory.ai/claude/

Connect xmemory's MCP server to Claude and your agents get xmemory's read and write tools with no custom code. This guide covers the **custom connector** for claude.ai and Claude Desktop (it also appears on the mobile apps once added), plus the **Claude Code** CLI.

## Claude (Desktop & claude.ai)

Add xmemory as a custom connector from claude.ai or Claude Desktop; once added, it shows up on the mobile apps too. The screenshots below are from Claude Desktop — claude.ai has the same layout.

The fastest way is the **Add to Claude.ai** button on your instance's **Connect** page in the [xmemory console](https://console.xmemory.ai) — it deep-links straight to the *Add custom connector* dialog with the name and MCP URL pre-filled. To add it manually, follow the steps below.

### 1) Open Customize → Connectors and add a connector

Open **Customize → Connectors** — **Connectors** sits under the **Customize** heading of the settings screen, on claude.ai and Claude Desktop alike. Then open the **Add** menu beside the Connectors heading and choose **Add custom connector**.

> Image: The Connectors screen under Customize with the Add menu open on Add custom connector

### 2) Name it and paste the MCP URL

Give the connector a name and paste your xmemory MCP URL:

```
https://mcp.xmemory.ai/instance/<instance_id>
```

An instance URL binds the tools to that instance up front. (To pick the instance interactively during login instead, use the root URL `https://mcp.xmemory.ai/`.) The optional OAuth fields under *Advanced settings* stay empty. Click **Add**.

> Image: The Add custom connector dialog with the xmemory MCP URL pasted in

### 3) Connect and sign in

The connector's page says it is not connected yet. Click **Connect** and complete the browser sign-in. That form is xmemory's own and asks for one thing: an **xmemory API key**, which you create on the **API Keys** page of the [console](https://console.xmemory.ai).

> Image: The xmemory connector page in Claude before connecting

### 4) Tools are ready

Once connected, xmemory's `read` and `write` tools are available in your chats. The connector's page lists every tool by group — set a whole group (or any single tool) to **Always allow**, **Needs approval**, or **Blocked**; **Custom** mixes per-tool choices within a group.

> Image: Tool permissions for the xmemory connector in Claude, with the group menu open on Always allow

## Claude Code (CLI)

For the Claude Code CLI, connect through the xmemory CLI: install it, sign in once by approving an emailed link, then register the instance through it:

```sh
uv tool install --upgrade xmemcli
xmemcli auth login --rc-dir "$HOME" --email <your-email>
claude mcp add xmemory-<FIRST8> -- xmemcli mcp <instance_id>
```

Skip the sign-in if `xmemcli --json status` already reports `authenticated: true` with its `rc_file` in your home directory; `--rc-dir "$HOME"` puts the key there, where the session-start hook reads it. If the install says its directory is not on your `PATH`, run `uv tool update-shell` and open a new terminal.

Name the server `xmemory-` plus the **first eight characters of the instance id** — the same name `xmemcli instance setup` prints for it; the [install guide](https://xmemory.ai/install/#claude-code) explains why a shared name collides.

Claude Code starts `xmemcli mcp`, which reads the CLI's credential on every connection, so the entry holds no key and needs no sign-in of its own. The [install guide](https://xmemory.ai/install/#claude-code) covers checking a CLI that is already installed.

Where the CLI cannot be installed or upgraded, register the instance URL directly — the command the console's **Connect** page shows:

```sh
claude mcp add --transport http xmemory-<FIRST8> https://mcp.xmemory.ai/instance/<instance_id>
```

The `/instance/<instance_id>` path binds the connection to that instance. Authorize it from inside a session with `/mcp`, or run `claude mcp login xmemory-<FIRST8>`; the page that opens asks for an xmemory API key from the console's **API Keys** page. For headless use (CI, scripts), pass a fixed API key instead by adding `--header "Authorization: Bearer <xmemory API key>"`.

See the full [MCP guide](https://xmemory.ai/mcp/) for both authentication paths, the complete tool list, and error handling.

## Other connection types

The steps above bind to a single instance (`/instance/<instance_id>`) and expose its `read`/`write` tools. The MCP server offers two other connection types, chosen by the URL you connect with:

- **Admin (fleet) tools** — connect with `https://mcp.xmemory.ai/admin` to create instances, list clusters, and manage instance metadata. Admin is global-only (there is no `/admin/<instance_id>`).
- **Status only** — connect with `https://mcp.xmemory.ai/status` for the read-only service-status tool.

In a connector, paste the admin (or status) URL instead of the instance URL — or paste the root `https://mcp.xmemory.ai/` and choose **Admin MCP** on the xmemory login page. For Claude Code, swap the URL in the `claude mcp add` command:

```sh
claude mcp add --transport http xmemory-admin https://mcp.xmemory.ai/admin
```

See the [MCP guide](https://xmemory.ai/mcp/#admin-tools) for the full admin tool list.
