MCP Quick Start

Every supported client runs the same local server, npx -y @mysten-incubation/memwal-mcp, and differs only in where the configuration lives. Pick your client below, add the server, restart, and sign in.

For regular Claude Desktop or web chat, use the OAuth custom connector instead of the local setup below. It needs no local Node.js or CLI. The Code tab inside Claude Desktop uses the Claude Code plugin guide.

Prerequisites

• You need Node.js 20 or later, because the server runs through npx with no install step.
• npx resolves the package name against the directory your client starts the server in, which is usually the project you have open. A project that contains an installed @mysten-incubation/memwal-mcp of its own would be run instead of the published package, and pinning a version in the command does not prevent it. The plugin avoids this by installing the pinned version into ~/.memwal/runtime and launching that absolute path; to get the same property without the plugin, install the version yourself outside any project and point command/args at the absolute entry point (see the package README).
• You need a Walrus Memory account. An unauthenticated memory-tool call returns sign-in instructions rather than signing you in, so ask the agent to run memwal_login and follow the URL it returns to connect your wallet. Config files carry no keys.

Set up your client

Client	Where the config lives	Setup
Claude Code	Managed by the CLI	claude mcp add --scope user memwal -- npx -y @mysten-incubation/memwal-mcp, or install the plugin for automatic-memory hooks
Claude Desktop	claude_desktop_config.json	Add the JSON block below; see Claude Desktop for the per-OS file path
Cursor	~/.cursor/mcp.json	Add the JSON block below; hooks are optional
Codex	~/.codex/config.toml	codex plugin marketplace add MystenLabs/MemWal then codex plugin add memwal@memwal-plugins for the plugin with automatic-memory hooks, or add the TOML block below for MCP-only
OpenCode	~/.config/opencode/opencode.json	Add the OpenCode block below
Antigravity	Plugin directory or MCP config	npx degit MystenLabs/MemWal/packages/mcp/plugin ~/.gemini/config/plugins/memwal, or the JSON block; see Antigravity

After any of these, restart the client (MCP servers load at startup) and ask the agent to run memwal_login.

Config blocks

Every client runs the same server and differs only in the file format. The server entry is the canonical configuration from the packages/mcp README, and a CI check keeps every copy in these docs in sync with it.

JSON clients

Claude Desktop, Cursor, and Antigravity's MCP config all take this shape:

{
  "mcpServers": {
    "memwal": {
      "command": "npx",
      "args": ["-y", "@mysten-incubation/memwal-mcp"]
    }
  }
}

Codex

Codex reads ~/.codex/config.toml:

[mcp_servers.memwal]
command = "npx"
args = ["-y", "@mysten-incubation/memwal-mcp"]

OpenCode

OpenCode reads ~/.config/opencode/opencode.json:

{
  "mcp": {
    "memwal": {
      "type": "local",
      "command": ["npx", "-y", "@mysten-incubation/memwal-mcp"],
      "enabled": true
    }
  }
}

Configure a namespace

Every recall runs inside one account and namespace. To keep a client's memories in their own space, set the MEMWAL_NAMESPACE environment variable in the server entry (env in JSON configs, environment in OpenCode), or pass "--namespace", "<name>" in args. Without it, memories go to the default namespace.

Verify

1. Open your client's MCP status view (for example /mcp in Claude Code) and confirm the status view lists memwal as connected with its tools.
2. Ask the agent to run memwal_health; it returns a fast connectivity check against the relayer.
3. State a durable fact, for example a package-manager preference, confirm the agent calls memwal_remember, then start a fresh session and confirm memwal_recall finds it.

If a step fails, run npx -y @mysten-incubation/memwal-mcp --help in a terminal to surface the real error, and set MEMWAL_MCP_DEBUG=1 in the server's environment for verbose logging. The Claude Code page carries the full troubleshooting FAQ; the errors apply to every client.