> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorycrystal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Understand the current and legacy MCP server paths, what they expose, and which client should use which path.

## Recommended: universal installer

Use the universal installer first. It can configure this target for hosted cloud or local Docker Convex and creates config backups before writing.

```bash theme={"system"}
curl -fsSL https://memorycrystal.ai/crystal | bash -s -- --targets generic-mcp
```

For native Windows PowerShell, use:

```powershell theme={"system"}
iwr https://memorycrystal.ai/install.ps1 -OutFile install.ps1
.\install.ps1 -Targets generic-mcp
```

For local data storage, add `--backend local` in Bash or `-Backend local` in PowerShell. See [Local-First Setup](/configuration/local-first).

An MCP server is a tool box your AI can open.
Memory Crystal gives that tool box memory tools like “remember this”, “search old conversations”, and “look inside a knowledge base”.

## What this means in practice

There are **two MCP server stories** in this repo:

### Current path

* `packages/mcp-server/`
* Streamable HTTP MCP
* best for modern MCP-capable clients

### Legacy path

* `mcp-server/`
* deprecated stdio/HTTP server
* still relevant for older compatibility paths like Claude Desktop

## Which clients use which path?

### Use the current Streamable HTTP MCP path for:

* Claude Code
* Codex CLI
* Factory Droid
* other clients that support Streamable HTTP MCP

### Use the deprecated stdio/HTTP package for:

* Claude Desktop
* older or compatibility-driven setups

When you launch the deprecated package as a command for a client, set `CRYSTAL_MCP_MODE=stdio`. Reserve `http` for the explicit local network listener.

## How it actually works

The current package (`packages/mcp-server`) wraps Memory Crystal's hosted HTTP API and exposes a Streamable HTTP MCP endpoint.

The deprecated package (`mcp-server`) exposes the older local stdio/HTTP form of the same memory tool surface.

Core tool areas include:

* recall and search
* remember and checkpoint
* wake/trace/stats
* knowledge-base list/query/import

## Retrieval contract

* `crystal_recall` and reasoning helpers are graph-aware blended memory lookups.
* `crystal_query_knowledge_base` is the dedicated path for named manuals, voice guides, transcripts, runbooks, and imported reference corpora.
* `crystal_search_messages` is retained transcript search and should be used for exact wording, not broad memory synthesis.
* `crystal_preflight` is recall with rule/lesson/decision filters and should include `projectId` or `repoSlug` for repo-specific work.
* `agentId`, `channel`, `projectId`, and `repoSlug` are scope inputs. Use them whenever the client knows the agent/client/repo boundary.
* KB `sourceRole` values such as `voice_style`, `persona_guardrail`, `canonical_reference`, and `client_context` are provenance and ranking signals.

## Universal installer path

The recommended first install path is the universal installer:

```bash theme={"system"}
curl -fsSL https://memorycrystal.ai/crystal | bash
```

Use it when you want Memory Crystal to detect MCP clients, ask before changing config, and offer cloud or local-first backend mode. The dedicated commands below remain useful for single-client installs and compatibility.

## Commands / examples

Current package local run example:

```bash theme={"system"}
MEMORY_CRYSTAL_API_URL=https://your-deployment.convex.site \
MEMORY_CRYSTAL_API_KEY=your_api_key_here \
npm run start --workspace packages/mcp-server
```

Example client registration:

```bash theme={"system"}
claude mcp add memory-crystal --transport http http://localhost:3100/mcp
```

```bash theme={"system"}
codex mcp add memory-crystal --url http://localhost:3100/mcp
```

## Common mistakes

* using the deprecated package when a client supports the current HTTP transport
* confusing hosted backend auth with local process config
* documenting Claude Desktop like it uses the same path as Claude Code

## Source of truth

Primary files behind this page:

* `packages/mcp-server/README.md`
* `packages/mcp-server/package.json`
* `packages/mcp-server/railway.toml`
* `mcp-server/README.md`
* `mcp-server/src/index.ts`