ctxvault-mcp

MCP Server for CtxVault — Give Claude, Codex, and Cursor persistent memory across sessions.

Quick Setup

Universal Interactive Setup (Recommended)

npx ctxvault-mcp setup

This prompts for target assistant (codex, claude-code, claude-desktop, cursor, or all) and your API key. It will then fetch your projects and let you pick one (defaults to a slug derived from the current folder name). If you do not have an API key yet, type open at the API key prompt and it opens https://ctxvault.dev/signup.

Interactive Login (No API key paste)

You can login with magic link and store a local session profile:

npx ctxvault-mcp login

Then manage projects interactively:

npx ctxvault-mcp projects
npx ctxvault-mcp use your-project --sync-default
npx ctxvault-mcp sync

This stores local profile state in ~/.config/ctxvault/mcp.json (or $XDG_CONFIG_HOME/ctxvault/mcp.json). Credentials are stored in OS keychain when available (macOS Keychain or Linux Secret Service), with file fallback only if keychain is unavailable.

You can also target one assistant directly:

npx ctxvault-mcp setup codex
npx ctxvault-mcp setup claude-code
npx ctxvault-mcp setup claude-desktop
npx ctxvault-mcp setup cursor

Codex (Manual)

codex mcp add ctxvault \
  --env CTXVAULT_API_KEY=cv_your_key \
  --env CTXVAULT_PROJECT=your-project \
  --env CTXVAULT_BASE_URL=https://ctxvault.dev \
  -- npx ctxvault-mcp

Claude Code (CLI)

Use the universal setup (recommended), or add with JSON (more reliable than -e flags):

claude mcp add-json -s user ctxvault '{"command":"npx","args":["ctxvault-mcp"],"env":{"CTXVAULT_API_KEY":"cv_your_key","CTXVAULT_PROJECT":"your-project","CTXVAULT_BASE_URL":"https://ctxvault.dev"}}'

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ctxvault": {
      "command": "npx",
      "args": ["ctxvault-mcp"],
      "env": {
        "CTXVAULT_API_KEY": "cv_your_key",
        "CTXVAULT_PROJECT": "your-project",
        "CTXVAULT_BASE_URL": "https://ctxvault.dev"
      }
    }
  }
}

Cursor

Add to Cursor MCP settings with the same config as Claude Desktop. If the Cursor CLI install fails on your machine, ctxvault-mcp setup cursor falls back to writing a local config file:

// .cursor/mcp.json
{
  "mcpServers": {
    "ctxvault": {
      "command": "npx",
      "args": ["ctxvault-mcp"],
      "env": {
        "CTXVAULT_API_KEY": "cv_your_key",
        "CTXVAULT_PROJECT": "your-project",
        "CTXVAULT_BASE_URL": "https://ctxvault.dev"
      }
    }
  }
}

It also adds .cursor/ to .gitignore so you don’t accidentally commit secrets.

Get Your API Key

1. Go to CtxVault
2. Sign up with your email (passwordless magic link)
3. Save the API key and project slug

Tools

Once connected, your AI assistant gets memory + account/project tools:

| Tool | Description | |------|-------------| | ctxvault_remember | Store a decision, convention, pattern, or lesson | | ctxvault_recall | Search memory for relevant context | | ctxvault_context | Get a full context pack for a topic | | ctxvault_list | List all memory items | | ctxvault_whoami | Show identity, role, scope, and accessible projects | | ctxvault_projects | List projects available to the current API key | | ctxvault_project_current | Show session active project, env project, and cloud default | | ctxvault_project_use | Switch project for this MCP session; optionally sync cloud default | | ctxvault_project_create | Create a project and optionally activate/sync it | | ctxvault_project_update | Update project name/description |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CTXVAULT_API_KEY | No | API key (starts with cv_) | | CTXVAULT_SESSION | No | Session token (cv_session) from magic-link verify | | CTXVAULT_PROJECT | No | Project slug override. If omitted, MCP resolves from cloud default/available projects. | | CTXVAULT_BASE_URL | No | API base URL (defaults to https://ctxvault.dev) |

At least one of CTXVAULT_API_KEY or CTXVAULT_SESSION is required. If neither is set, MCP falls back to local saved login profile.

Troubleshooting

Validate your config:

npx ctxvault-mcp doctor

Inside your assistant, run:

1. ctxvault_projects to see available slugs
2. ctxvault_project_use with the chosen slug
3. ctxvault_project_current to confirm active/default alignment

Reset local auth:

npx ctxvault-mcp logout

License

MIT