Skip to main content
Memory Crystal provides two MCP server options depending on your use case:

stdio / npm package

The @memorycrystal/mcp-server npm package. Best for tools like Claude Desktop that launch MCP servers as local processes.

Streamable HTTP server

A standalone HTTP server at http://localhost:3100/mcp. Best for connecting multiple clients or running the server persistently.

​
stdio / npm package

​
Install

npm install -g @memorycrystal/mcp-server

​
Configure

Set these environment variables before running:
VariableRequiredDescription
MEMORY_CRYSTAL_API_KEYYesYour Memory Crystal API key
MEMORY_CRYSTAL_API_URLYesYour Memory Crystal backend URL, e.g. https://<your-deployment>.convex.site

​
Run

MEMORY_CRYSTAL_API_URL=https://your-deployment.convex.site \
MEMORY_CRYSTAL_API_KEY=your-api-key-here \
crystal-mcp

​
Streamable HTTP server

The Streamable HTTP server is a standalone Node.js service that exposes Memory Crystal over MCP’s HTTP transport. Run it once and connect any number of MCP clients to it.

​
Configure

VariableDefaultDescription
MEMORY_CRYSTAL_API_KEY—Your Memory Crystal API key. Required unless clients send Authorization: Bearer <key>
MEMORY_CRYSTAL_API_URL—Your Memory Crystal backend URL
PORT3100Port the server listens on
HOST0.0.0.0Host the server binds to

​
Run

From the monorepo root: 
MEMORY_CRYSTAL_API_URL=https://your-deployment.convex.site \
MEMORY_CRYSTAL_API_KEY=your-api-key-here \
npm run start --workspace packages/mcp-server
The server starts two endpoints:
EndpointPurpose
http://localhost:3100/mcpMCP Streamable HTTP endpoint
http://localhost:3100/healthHealth check

​
Health check

curl http://localhost:3100/health
Use this to confirm the server is running before connecting clients.
The Streamable HTTP server is stateless — each request is independent. You can run multiple instances behind a load balancer if needed.

​
Available tools

Both server variants expose the same set of crystal_* tools:
ToolWhat it does
crystal_wakeSession startup briefing — loads active goals, recent decisions, and pending work
crystal_rememberStore a memory manually — decisions, facts, lessons, anything worth keeping
crystal_recallSemantic search across long-term memory
crystal_recentFetch recent messages for short-term context
crystal_search_messagesSearch verbatim conversation history
crystal_what_do_i_knowSnapshot of everything known about a topic
crystal_why_did_weDecision archaeology — understand why a past decision was made
crystal_who_ownsFind who owns a file, module, or area
crystal_explain_connectionExplain the relationship between two concepts
crystal_dependency_chainTrace dependency chains between entities
crystal_preflightPre-flight check before risky actions — returns relevant rules and lessons
crystal_traceTrace a memory back to its source conversation
crystal_checkpointSave a session checkpoint
crystal_forgetArchive (soft-delete) a memory
crystal_statsMemory and usage statistics
crystal_list_knowledge_basesList available knowledge bases
crystal_query_knowledge_baseSearch within a specific knowledge base
crystal_import_knowledgeImport reference chunks into a knowledge base
The stdio package also exposes crystal_edit and crystal_ideas / crystal_idea_action for editing existing memories and managing Organic idea discoveries.