Skip to main content
Claude Code supports MCP servers at both the project level and globally. You can add Memory Crystal using a config file or the claude mcp add CLI command.

​
Prerequisites

Install the @memorycrystal/mcp-server npm package: 
npm install -g @memorycrystal/mcp-server
You’ll also need your Memory Crystal API key and backend URL. Find these in your Memory Crystal dashboard.

​
Claude Code

Add a .claude/mcp.json file to your project:
{
  "mcpServers": {
    "memory-crystal": {
      "command": "crystal-mcp",
      "env": {
        "MEMORY_CRYSTAL_API_KEY": "your-api-key-here",
        "MEMORY_CRYSTAL_API_URL": "https://your-deployment.convex.site"
      }
    }
  }
}
This config applies to the current project only. Commit it to your repository to share the setup with your team.

​
Codex CLI

Add Memory Crystal to Codex CLI by pointing it at the Streamable HTTP server: 
codex mcp add memory-crystal --url http://localhost:3100/mcp
Start the Streamable HTTP server before running Codex sessions.

​
Session startup with crystal_wake

Call crystal_wake at the start of every session to load your current context: 
crystal_wake(channel="your-project-name")
The wake briefing returns:
  • Active goals and pending work
  • Recent decisions made in previous sessions
  • Any rules or lessons relevant to the current project
Make crystal_wake the first tool call in every Claude Code or Codex session. Without it, the agent starts each session without any memory of prior context.

​
Verify

After configuring, confirm Memory Crystal is connected by asking the agent to call crystal_stats. It should return your memory usage statistics without errors. If the tools don’t appear, check that:
  • crystal-mcp is on your PATH (run which crystal-mcp in a terminal), or the Streamable HTTP server is running on the expected port
  • The MEMORY_CRYSTAL_API_KEY and MEMORY_CRYSTAL_API_URL values are correct
  • The config file is valid JSON