Quick Setup

Sent here by a 401/404 error from core.mnemoverse.com?

You (or your MCP client) used the REST base URL as an MCP connector address. They are different surfaces of the same memory:

You wanted	Use this URL
MCP connector (Claude, ChatGPT, editors — OAuth sign-in)	https://mcp.mnemoverse.com/mcp
REST API (curl, SDKs, scripts — X-Api-Key header)	https://core.mnemoverse.com/api/v1

The REST base speaks JSON over HTTPS with an API key — it is not an MCP server and cannot complete an MCP client's OAuth discovery. Paste https://mcp.mnemoverse.com/mcp into the connector field instead — see Step 1B (ChatGPT: custom MCP server).

For AI Agents

Machine-readable docs (plain text, no auth): mnemoverse.com/docs/llms.txt

Set up Mnemoverse persistent memory in your AI tool. Pick your tool below.

What You Need

Two setup paths exist for Mnemoverse memory. Pick one:

• Path A — Local MCP server. You run @mnemoverse/mcp-memory-server over stdio inside the host tool, authenticated either with a mk_live_* API key from the console, or, in VS Code (and VSCodium) with the extension's default local connection, keylessly through the Mnemoverse Agent Memory extension's browser sign-in (no key to paste). This is the path documented below in Step 1.
• Path B — Remote MCP server + one-click OAuth (live). The host tool connects to https://mcp.mnemoverse.com/mcp over streamable HTTP and authorises via OAuth 2.1 + PKCE against auth.mnemoverse.com/api/auth — no API key copy-paste. The endpoint and its OAuth discovery chain are deployed and serving. Where a client's directory has no Mnemoverse listing, you add the URL yourself; ChatGPT's Plugin Directory does not list Mnemoverse, so in ChatGPT the URL goes into a custom MCP server. See the Remote MCP Server page, with per-client configs in Step 1B.

If you do not know which path you want: pick B when the host can add a remote MCP server by URL and open a browser sign-in (Claude Code, Claude Desktop, claude.ai, Cursor, VS Code, ChatGPT): there is no key to ask the user for and nothing to install. Pick A when the host cannot, when the machine has no browser, or when the user asks for an API key. You can move between them without losing memories — same account, same atoms. (The two paths expose the same tool set; see Available Tools. One host is the exception: in ChatGPT the remote connector does not offer vault_list (Where each tool works).)

Authentication at a glance

The same memory, four ways to authenticate — pick by your tool:

Method	What you paste	Works in	Setup
Remote OAuth connector	nothing (browser sign-in)	any compliant MCP client; in Cursor, Add to Cursor, then Connect in Customize	Remote MCP Server · Step 1B · Cursor
Keyless extension sign-in	nothing (browser sign-in)	VS Code 1.102+ and VSCodium, with the extension (where it works)	VS Code
Local package + API key	a mk_live_ key	every MCP client, scripts, CI	Step 1
ChatGPT Custom GPT (workspace plans only)	a mk_live_ key	ChatGPT Business/Enterprise/Edu	ChatGPT

All four resolve to the same account and the same atoms — write with one, recall with another. The API-key methods need a free key from console.mnemoverse.com; the browser methods just need an account.

What you need for either path:

1. Path B: a Mnemoverse account at console.mnemoverse.com — no manual key needed; OAuth grants the token. Path A: a Mnemoverse API key (starts with mk_live_). If the user hasn't provided one, tell them to get a free key at console.mnemoverse.com.
2. Path B needs nothing installed locally. Path A: Node.js (18+) on the machine running the host tool: npx launches @mnemoverse/mcp-memory-server locally.
3. Know which tool you are running in (see below).

Step 1: Detect Your Environment

Determine which AI tool you are running in. If it can add a remote MCP server by URL and open a browser sign-in, start with Step 1B (Path B): there is no key to ask the user for. This section covers Path A (local stdio with an API key) for the hosts that cannot, with per-host notes on the keyless path.

Claude Code

No key and nothing to install: the hosted server is one command, claude mcp add --scope user --transport http mnemoverse https://mcp.mnemoverse.com/mcp, with sign-in steps under Claude Code (remote). For the local server with an API key, run this command:

claude mcp add mnemoverse --scope user \
  -e MNEMOVERSE_API_KEY=mk_live_USER_KEY \
  -- npx -y @mnemoverse/mcp-memory-server@latest

On Windows (PowerShell), run the same command as one line — PowerShell does not read the \ line continuations:

claude mcp add mnemoverse --scope user -e MNEMOVERSE_API_KEY=mk_live_USER_KEY -- npx -y @mnemoverse/mcp-memory-server@latest

Replace mk_live_USER_KEY with the actual key, restart Claude Code, then run claude mcp list to confirm the connection. See Claude Code troubleshooting if it does not show as connected.

Cursor

Recommended — hosted OAuth, no API key: Add Mnemoverse to Cursor, then sign in in the browser. Memories written in Cursor are available in Claude Code when both clients use the same Mnemoverse account.

Alternative — local server + API key: create (or merge into) the global file ~/.cursor/mcp.json in the user's home directory. Do not use a project-level .cursor/mcp.json for this: it holds the key, and that file is committed with the repository unless it is excluded.

{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_USER_KEY"
      }
    }
  }
}

Tell the user to restart Cursor after you create this file.

VS Code

The easiest path for VS Code is the keyless Mnemoverse Agent Memory extension: install it and click Sign In, with no API key to paste. The manual .vscode/mcp.json below is the alternative (it needs an API key). The extension does not cover every editor: Cursor's keyless path is the hosted server in Cursor (remote), and in Devin Desktop (formerly Windsurf) the extension cannot add MCP servers at all (where the extension works).

Use the file .vscode/mcp.json in the project root, but never write a literal key into it: VS Code documents that file as one to include in source control, so a pasted key is committed with the repository. The inputs entry below makes VS Code prompt the user for the key on first start and keep it in its own secret storage instead of the file. Tell the user the prompt will appear once.

VS Code — the VS Code extension signs in through the browser and needs no key; that's the default path. In VS Code's non-interactive Agent Host mode, servers that prompt for inputs like this one are not started; for unattended use there, put the key in the environment of the process that launches VS Code instead. To wire the MCP server directly instead, add this to .vscode/mcp.json (note: VS Code uses servers, not mcpServers). Never put a literal mk_live_ key in that file — it's committed with the repo. The inputs entry below prompts for the key instead: VS Code masks what you type and stores it in its own secret storage, not in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mnemoverse-api-key",
      "description": "Mnemoverse API key (starts with mk_live_), for this local package only: the hosted server https://mcp.mnemoverse.com/mcp signs in with OAuth and takes no key. Optional to install and inspect — the server starts and lists its tools without a key; every actual tool call requires one. Get one free in ~30s at https://console.mnemoverse.com",
      "password": true
    }
  ],
  "servers": {
    "mnemoverse": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@mnemoverse/mcp-memory-server@latest"
      ],
      "env": {
        "MNEMOVERSE_API_KEY": "${input:mnemoverse-api-key}",
        "MNEMOVERSE_API_URL": "https://core.mnemoverse.com/api/v1"
      }
    }
  }
}

Tell the user to restart VS Code after you create this file.

Claude Desktop

Tell the user to add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_USER_KEY"
      }
    }
  }
}

Claude Desktop requires manual config edit and restart.

Devin Desktop (formerly Windsurf)

Create or edit ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows). Devin Local, Devin Desktop's own agent, reads MCP servers from this Devin CLI file. By default Devin also imports MCP servers from the older Windsurf file ~/.codeium/windsurf/mcp_config.json and from Claude Code (.mcp.json, ~/.claude.json) and Cursor (.cursor/mcp.json) config files. Check those first, or run devin mcp list if Devin CLI is installed: if a mnemoverse server is already there, it needs no second copy.

{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": {
        "MNEMOVERSE_API_KEY": "mk_live_USER_KEY"
      }
    }
  }
}

Tell the user to restart Devin Desktop after you create this file.

ChatGPT

You cannot self-configure inside ChatGPT. ChatGPT on the web connects only to remote MCP servers, so the local package does not apply there; OpenAI documents local MCP apps inside a plugin on ChatGPT Desktop, but the Mnemoverse package has not been tested that way. Tell the user to follow the manual setup guide: ChatGPT Integration. Its main path is the remote connector added as a custom MCP server, with browser sign-in and no API key (see Step 1B — ChatGPT); in a Business, Enterprise or Edu workspace, a Custom GPT with Actions and an API key is the alternative.

Other Tools

If the tool asks for an MCP server URL, that is https://mcp.mnemoverse.com/mcp, with a browser sign-in and no key: see Step 1B. Otherwise, if the tool supports MCP, use the Cursor config format (it is the most common) with an API key. If the tool does not support MCP, use the REST API directly (these are REST endpoints, not MCP URLs):

# Write a memory
curl -X POST https://core.mnemoverse.com/api/v1/memory/write \
  -H "X-Api-Key: mk_live_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Test memory", "concepts": ["test"]}'

# Read memories
curl -X POST https://core.mnemoverse.com/api/v1/memory/read \
  -H "X-Api-Key: mk_live_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "test", "top_k": 5}'

Step 1B: One-click OAuth Connect

Live — the endpoint is serving

The remote MCP endpoint at https://mcp.mnemoverse.com/mcp and its OAuth discovery chain (auth.mnemoverse.com/api/auth) are deployed and serving. Claude's connector directory and ChatGPT's Plugin Directory, which replaced the App Directory, do not list Mnemoverse: use the static config below or Path A. The canonical host is published in data/facts.json under mcp.remote.endpoint.

How the connect actually works: the host tool POSTs to https://mcp.mnemoverse.com/mcp, gets a 401 + WWW-Authenticate: Bearer challenge (a GET with no credentials gets the same one: probed on 2026-10-21, a GET and a POST each returned 401, that header and a JSON body with "error": "missing_token"), walks the OAuth discovery chain to auth.mnemoverse.com/api/auth, opens the consent screen on console.mnemoverse.com (scopes: openid profile email memory:read memory:write offline_access), and stores the access + refresh tokens locally. No API key is ever copied; the host tool is the OAuth client. Compliant clients self-register via Dynamic Client Registration (RFC 7591) at the authorization server; DCR is host-allowlisted — see which clients can sign in for the current list. A client whose redirect host is not on the allowlist uses the static config below instead. Section 11 of the Privacy Policy describes the data flow end-to-end.

Claude Code (remote)

The agent self-configures with:

claude mcp add --scope user --transport http mnemoverse https://mcp.mnemoverse.com/mcp

Keep --scope user: without it the server is added for the current directory only. A server added this way while a Claude Code session is running is not loaded by that session: in a run on 2026-10-18 (Claude Code 2.1.283), /mcp listed it only after claude was started again. If you ran the command from inside the user's session, tell the user to exit and start claude again first.

Adding the connector does not start sign-in: until the user signs in, claude mcp list shows mnemoverse as ! Needs authentication and no memory tools are available. To sign in, tell the user to start a Claude Code session, run /mcp, select mnemoverse, choose Authenticate, and approve the consent screen that opens in the browser. On Claude Code 2.1.186 or later, claude mcp login mnemoverse runs the same sign-in from a shell. In an interactive session, Claude Code may also give you an authenticate tool for mnemoverse while the server needs authentication. Calling that tool starts the sign-in and returns a sign-in URL without opening the browser, so give the URL to the user to open. Claude Code stores and refreshes the token. No -e MNEMOVERSE_API_KEY needed. Do not report setup as complete until claude mcp list shows mnemoverse as ✔ Connected.

Claude Desktop (remote)

Tell the user to open Customize → Connectors, click +, then Add custom connector, and paste https://mcp.mnemoverse.com/mcp as the URL. Or give them the Connect to Claude link, which opens that dialog on claude.ai with the name and URL filled in. Free plans allow one custom connector. Claude Desktop drives the OAuth flow on first use. No JSON config file edit needed for the remote path.

Cursor (remote)

Create .cursor/mcp.json in the project root:

{
  "mcpServers": {
    "mnemoverse": {
      "url": "https://mcp.mnemoverse.com/mcp"
    }
  }
}

Cursor detects the HTTP URL. Tell the user to restart Cursor after creating this file. To sign in, the user opens Customize in the sidebar and clicks Connect next to mnemoverse: Cursor walks the OAuth discovery chain and opens the consent screen in the default browser. The entry holds no key, so it is safe in a project file. For every project and every Cursor window, including the Agents Window, the same entry goes in ~/.cursor/mcp.json; the user can add it there with the one-click link https://cursor.com/install-mcp?name=mnemoverse&config=eyJ1cmwiOiJodHRwczovL21jcC5tbmVtb3ZlcnNlLmNvbS9tY3AifQ== (Cursor).

VS Code (remote)

Create .vscode/mcp.json in the project root:

{
  "servers": {
    "mnemoverse": {
      "type": "http",
      "url": "https://mcp.mnemoverse.com/mcp"
    }
  }
}

The "type": "http" field is what tells VS Code to use the streamable-HTTP transport with OAuth discovery; without it, VS Code defaults to stdio and the install fails. Tell the user to restart VS Code after creating this file.

ChatGPT (custom MCP server)

You cannot self-configure inside ChatGPT. Mnemoverse is not listed in ChatGPT's Plugin Directory, so there is no entry to search for there; the user adds the connector URL as a custom MCP server. Tell the user to:

1. Check what their plan allows. In a workspace, its permissions decide who can add the server, and some plans cannot save: see MCP connector (custom MCP server).
2. Open ChatGPT Plugins, select +, then Add custom MCP server, enter a name, and under Connection enter https://mcp.mnemoverse.com/mcp, with OAuth as the authentication.
3. Select Create as a plugin, sign in to Mnemoverse in the browser, and approve the requested scopes.
4. Install the plugin, then in a new conversation type @ and select it.

In a Business, Enterprise or Edu workspace, a Custom GPT with OpenAPI Actions and an API key is the alternative: ChatGPT Integration.

Devin Desktop (remote)

Create or edit ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows):

{
  "mcpServers": {
    "mnemoverse": {
      "url": "https://mcp.mnemoverse.com/mcp"
    }
  }
}

OAuth sign-in to the hosted connector from Devin Local is not verified yet. Devin documents a browser sign-in for OAuth servers, but we have not run it against Mnemoverse, so do not report setup as complete until a memory tool answers. If sign-in does not complete, use the API-key entry under Devin Desktop instead. Tell the user to restart Devin Desktop after creating this file.

Other Tools (remote)

If the host tool supports remote MCP servers (streamable HTTP + OAuth 2.1), point it at https://mcp.mnemoverse.com/mcp. The OAuth discovery chain follows RFC 9728 (protected resource metadata) and OIDC for the authorization server — anything compliant connects without per-tool hand-tuning.

Distribution Channels

The single source of truth for the channel registry (Official MCP Registry, Smithery, PulseMCP, mcp.so, awesome-mcp-servers, Glama, Anthropic Connectors Directory, OpenAI Plugin Directory, formerly the ChatGPT App Directory) lives in mnemoverse-distribution/channels/distribution-channels-2026.md. The currently-listed clients on the home page and in data/facts.json under clients.mcp reflect that registry.

A channel in the registry is not necessarily a channel that lists Mnemoverse. The Anthropic Connectors Directory (Claude's connector directory) and the OpenAI Plugin Directory do not list it: in those clients you add the remote URL yourself, as in Step 1B. Either path, the local package with an API key or the remote connector with a browser sign-in, reaches the same memory store.

Step 2: Verify

After setup, test by writing and reading a memory:

1. Store: "Remember that this is a test memory for setup verification"
2. Read: "What test memories do I have?"

If the read returns the test memory, setup is complete.

On Path A with an API key, the key alone can be checked first. Check your API key gives a bash and a PowerShell form that ask the user for the key at a masked prompt; if the API refuses the key, its answer names the cause.

Step 3: Tell the User

Confirm to the user:

• Memory is configured and working
• Memories persist across sessions
• Same memories are accessible from any tool signed in to the same account (API key or OAuth)
• Memory is used without reminders once the memory rules are in the agent's instructions; offer to add them (Make Your Agent Use Memory)

Available Tools After Setup

Path A (local) exposes 11 tools and Path B (remote) exposes 11. In ChatGPT, Path B exposes 10: every tool except vault_list (Where each tool works). The MCP Server page lists every tool and what it does.

Path A (local stdio) and Path B (remote OAuth) now expose the same tool set, apart from that ChatGPT exception; the earlier local/remote asymmetry is gone. Deleting a memory or wiping a domain is no longer an MCP tool on either path: it's REST-administrative only, called directly against the API rather than through a memory tool (see API Reference). The Beta shared-room tools (memory_create_room, memory_invite_to_room, memory_join_room, memory_list_rooms) are non-destructive and ship on both paths — see Join a shared room below. Per-tool annotations (readOnlyHint / destructiveHint / idempotentHint) are otherwise consistent across both transports.

Join a shared room (Beta)

Beta — shared rooms

A room is a memory pool shared across separate Mnemoverse accounts. Members address it by putting xroom:<room_id> in the domain field of memory_write / memory_read — no new endpoint, and no separate tool call to read or write it. Creating a room, inviting, and joining ship as three tools on both paths (Path A local and Path B remote); the feature is in beta. The Rooms page is the full reference for the address format, the two membership scopes (read / read_write), billing (usage is billed to the caller who makes the request, never the room owner), and the error envelope.

Three tools drive the flow — memory_create_room, memory_invite_to_room, and memory_join_room.

Owner — create a room and mint an invite:

1. memory_create_room({ name }) returns the room's room_id (shape room_<ulid>) and its address (xroom:<room_id>).
2. memory_invite_to_room({ room_id, scope }) mints a share code (mnvr_...) plus a ready-to-forward share_message. scope is read or read_write (default read_write) and is baked into the code at mint — the invitee gets exactly that role. Both paths default to one redemption and a 7-day expiry, and both accept expires_in_days and max_uses (1 to 1000) when the owner intentionally needs more than one redemption.
3. Forward the share_message — it carries the code and a join link — to whoever you're adding, over any channel.

Joiner — redeem the code, then use the room:

1. Their agent calls memory_join_room({ code }) with the mnvr_... code. The joiner's identity comes from their own auth, not the code — the code only carries the room and the role. Joining returns the room's address (xroom:<room_id>).
2. From then on, the joiner reads and writes the shared pool by passing domain: "xroom:<room_id>" on memory_write / memory_read — the same two tools you already use, with one extra field.

Self-installing invite

The invite is designed to set itself up. The recipient can paste the share_message straight to their own assistant. If that assistant isn't connected to Mnemoverse yet, it first follows Step 1B to add the Mnemoverse remote connector — no account needed up front; the first OAuth sign-in creates one — and then calls memory_join_room with the code. One paste, and the recipient's agent is in the room.

Being in a room does not change the memory habit: an agent won't reach for room memory unless told to. Point it at the room's domain in your project instructions, and set the general recall-and-save rule from Make Your Agent Use Memory.

Related

• MCP server reference — what each tool does, schemas, error codes
• Claude integration — Claude Code + Desktop details
• ChatGPT integration — the custom MCP server connector, or Custom GPT Actions in a workspace
• Cursor, VS Code & Devin Desktop (Windsurf) — editor specifics
• Privacy Policy §11 — connector data flow (per-tool retention, OAuth, sub-processors)
• Rooms — share one memory pool across accounts by passing xroom:<room_id> as the domain