> ## 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.

# Environment Variables

> Key environment variables for hosted MCP usage, self-hosting, and backend services.

These are the labels that tell your self-hosted setup where to connect and which secrets to use.

## What this means in practice

Memory Crystal uses several environment variables across the backend, MCP layers, and plugin/install flows.

## Most important variables

### API keys

* `GEMINI_API_KEY` — Google Gemini API key for Gemini-backed embeddings
* `OPENROUTER_API_KEY` — optional key for organic model features and unified provider routing
* `OPENAI_API_KEY` — still present in parts of the repo and some workflows
* `MEMORY_CRYSTAL_API_KEY` — preferred client-facing API key variable for MCP clients

## Backend URLs

* `CONVEX_URL` — Convex deployment URL
* `MEMORY_CRYSTAL_API_URL` — preferred client-facing backend base URL for MCP clients

Use `MEMORY_CRYSTAL_*` names for client setup and provider-specific names for backend provider keys.

## MCP / local runtime

* `CRYSTAL_MCP_MODE`
* `CRYSTAL_MCP_HOST`
* `CRYSTAL_MCP_PORT`

## Embeddings / provider selection

* `EMBEDDING_PROVIDER` — currently important for backend behavior
* `GEMINI_EMBEDDING_MODEL`

## Local content / storage

* `OBSIDIAN_VAULT_PATH`

## Example

From `.env.example`:

```env theme={"system"}
CONVEX_URL=https://your-deployment.convex.cloud
GEMINI_API_KEY=
OPENROUTER_API_KEY=
GEMINI_EMBEDDING_MODEL=gemini-embedding-2-preview
OPENAI_API_KEY=sk-...
OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault
CRYSTAL_MCP_MODE=stdio
CRYSTAL_MCP_HOST=127.0.0.1
CRYSTAL_MCP_PORT=8788
EMBEDDING_PROVIDER=gemini
MEMORY_CRYSTAL_API_KEY=
MEMORY_CRYSTAL_API_URL=https://your-deployment.convex.site
```

## How it actually works

Different variables matter to different layers:

* backend/runtime
* MCP client/server setup
* plugin installation and local health checks

For local command-launched MCP, use `CRYSTAL_MCP_MODE=stdio`.
Use `CRYSTAL_MCP_MODE=http` only when you explicitly want the deprecated local network MCP listener.

## Commands / examples

Example check:

```bash theme={"system"}
npm run crystal:doctor
```

## Doctor script behavior

The repo's doctor/smoke checks read these variables and will fail or warn when key values are missing.

For example, with `EMBEDDING_PROVIDER=gemini`, backend semantic recall expects a valid `GEMINI_API_KEY`. OpenClaw plugins and MCP clients should not need a Gemini key; they authenticate to Memory Crystal with `MEMORY_CRYSTAL_API_KEY`.

## Related docs

* [Installation](/installation)
* [Railway Deployment](/self-hosting/railway)
* [MCP Server](/integrations/mcp-server)

## Source of truth

* `.env.example`
* `scripts/crystal-doctor.sh`
* `packages/mcp-server/README.md`
* `mcp-server/README.md`