MCP Server Configuration Guide

MCP Server Configuration Guide

How to configure Aleph as an MCP server in all major MCP-compatible clients: Cursor, VS Code, Claude Desktop, Codex CLI, Windsurf, Kimi CLI, and others.

Quick Start (Full Power Mode)

For maximum capability without needing to configure workspace roots:

{
  "mcpServers": {
    "aleph": {
      "command": "aleph",
      "args": ["--enable-actions", "--workspace-mode", "any", "--tool-docs", "concise"]
    }
  }
}

This enables:

• All action tools (read_file, write_file, run_command, run_tests)
• Any git repo access (not limited to a single workspace root)
• Concise tool descriptions (cleaner MCP tool list)

Shared Sub-Query Sessions (Live Sandbox)

If you want CLI sub-agents spawned via sub_query to access the same live Aleph session (tools, contexts, and sandbox state), enable streamable HTTP sharing:

{
  "mcpServers": {
    "aleph": {
      "command": "aleph",
      "args": ["--enable-actions", "--workspace-mode", "any", "--tool-docs", "concise"],
      "env": {
        "ALEPH_SUB_QUERY_SHARE_SESSION": "true",
        "ALEPH_SUB_QUERY_HTTP_PORT": "8765",
        "ALEPH_SUB_QUERY_MCP_SERVER_NAME": "aleph_shared"
      }
    }
  }
}

Notes:

• The Aleph server spins up a local streamable HTTP endpoint on demand.
• CLI sub-agents (claude/codex/gemini) are pointed at that live server automatically.
• Customize host/path with ALEPH_SUB_QUERY_HTTP_HOST and ALEPH_SUB_QUERY_HTTP_PATH if needed.
• Tools are exposed under the server name you choose (default: aleph_shared).
• aleph_shared avoids conflicts with an existing aleph stdio entry in Codex config.
• For Claude, the shared session is passed via --mcp-config and --strict-mcp-config flags.

For even higher limits:

{
  "args": [
    "--enable-actions", "--workspace-mode", "any", "--tool-docs", "concise",
    "--timeout", "120", "--max-output", "100000"
  ]
}

Per-Client Configuration

Every client below uses the same core args. Only the file location and format differ. Replace /path/to/your-project with your actual project root.

Cursor

Config file:

• macOS / Linux: ~/.cursor/mcp.json
• Windows: %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "aleph": {
      "command": "aleph",
      "args": [
        "--workspace-root", "/path/to/your-project",
        "--enable-actions",
        "--tool-docs", "concise"
      ]
    }
  }
}

VS Code

Config file:

• macOS / Linux: ~/.vscode/mcp.json
• Windows: %USERPROFILE%\.vscode\mcp.json

{
  "mcpServers": {
    "aleph": {
      "command": "aleph",
      "args": [
        "--workspace-root", "/path/to/your-project",
        "--enable-actions",
        "--tool-docs", "concise"
      ]
    }
  }
}

Claude Desktop

Config file:

• macOS / Linux: ~/.claude/settings.json
• Windows: %USERPROFILE%\.claude\settings.json

Auto-discovery (simplest):

aleph-rlm install claude-code

Then restart Claude Desktop.

Manual:

{
  "mcpServers": {
    "aleph": {
      "command": "aleph",
      "args": [
        "--workspace-root", "/path/to/your-project",
        "--enable-actions",
        "--tool-docs", "concise"
      ]
    }
  }
}

Option 1: Download docs/prompts/aleph.md and save to:

• macOS / Linux: ~/.claude/commands/aleph.md
• Windows: %USERPROFILE%\.claude\commands\aleph.md

Option 2: From installed package:

# macOS / Linux
mkdir -p ~/.claude/commands
cp "$(python -c "import aleph; print(aleph.__path__[0])")/../docs/prompts/aleph.md" \
  ~/.claude/commands/aleph.md

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\commands"
$alephPath = python -c "import aleph; print(aleph.__path__[0])"
Copy-Item "$alephPath\..\docs\prompts\aleph.md" "$env:USERPROFILE\.claude\commands\aleph.md"

This enables the /aleph command for structured reasoning workflows.

Codex CLI

Config file:

• macOS / Linux: ~/.codex/config.toml
• Windows: %USERPROFILE%\.codex\config.toml

[mcp_servers.aleph]
command = "aleph"
args = ["--enable-actions", "--tool-docs", "concise"]

With a fixed workspace root:

[mcp_servers.aleph]
command = "aleph"
args = [
  "--workspace-root", "/path/to/your-project",
  "--enable-actions",
  "--tool-docs", "concise"
]

Option 1: Download docs/prompts/aleph.md and save to:

• macOS / Linux: ~/.codex/skills/aleph/SKILL.md
• Windows: %USERPROFILE%\.codex\skills\aleph\SKILL.md

Option 2: From installed package:

# macOS / Linux
mkdir -p ~/.codex/skills/aleph
cp "$(python -c "import aleph; print(aleph.__path__[0])")/../docs/prompts/aleph.md" \
  ~/.codex/skills/aleph/SKILL.md

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\skills\aleph"
$alephPath = python -c "import aleph; print(aleph.__path__[0])"
Copy-Item "$alephPath\..\docs\prompts\aleph.md" "$env:USERPROFILE\.codex\skills\aleph\SKILL.md"

This enables the $aleph command in Codex.

Kimi CLI

Add via the command line:

kimi mcp add --transport stdio aleph -- \
  aleph --enable-actions --tool-docs concise --workspace-root /path/to/your-project

Or edit ~/.kimi/mcp.json directly:

{
  "mcpServers": {
    "aleph": {
      "transport": "stdio",
      "command": "aleph",
      "args": [
        "--enable-actions", "--tool-docs", "concise",
        "--workspace-root", "/path/to/your-project"
      ]
    }
  }
}

Kimi CLI searches for skills in these locations (in order):

1. ~/.config/agents/skills/
2. .agents/skills/ (project root)
3. ~/.agents/skills/
4. ~/.kimi/skills/
5. ~/.claude/skills/
6. ~/.codex/skills/
7. .kimi/skills/ (project root)
8. .claude/skills/ (project root)
9. .codex/skills/ (project root)

User-level (recommended):

mkdir -p ~/.config/agents/skills/aleph
cp "$(python -c "import aleph; print(aleph.__path__[0])")/../docs/prompts/aleph.md" \
  ~/.config/agents/skills/aleph/SKILL.md

Project-level:

mkdir -p .agents/skills/aleph
cp "$(python -c "import aleph; print(aleph.__path__[0])")/../docs/prompts/aleph.md" \
  .agents/skills/aleph/SKILL.md

Override the search path with --skills-dir.

Windsurf

Standard MCP configuration:

{
  "mcpServers": {
    "aleph": {
      "command": "aleph",
      "args": [
        "--workspace-root", "/path/to/your-project",
        "--enable-actions",
        "--tool-docs", "concise"
      ]
    }
  }
}

Cline / Continue.dev

These clients support standard MCP configuration. Check their documentation for exact file locations and format.

Generic MCP Client

Key parameters:

Parameters Reference

Sub-Query Backends

sub_query can use an API backend or a local CLI backend. When ALEPH_SUB_QUERY_BACKEND is auto (default), Aleph chooses the first available:

1. codex CLI -- if installed
2. gemini CLI -- if installed
3. claude CLI -- if installed (deprioritized in MCP/sandbox contexts)
4. API -- if API credentials are available (fallback)

API Configuration

The API backend uses OpenAI-compatible endpoints only:

Quick Setup Examples

# OpenAI
export ALEPH_SUB_QUERY_API_KEY=sk-...
export ALEPH_SUB_QUERY_MODEL=your-model-name

# Groq (fast inference)
export ALEPH_SUB_QUERY_API_KEY=gsk_...
export ALEPH_SUB_QUERY_URL=https://api.groq.com/openai/v1
export ALEPH_SUB_QUERY_MODEL=llama-3.3-70b-versatile

# Local LLM (Ollama, LM Studio, etc.)
# Make sure your local server is running and the model is available.
export ALEPH_SUB_QUERY_API_KEY=ollama   # any non-empty value
export ALEPH_SUB_QUERY_URL=http://localhost:11434/v1
export ALEPH_SUB_QUERY_MODEL=llama3.2

All Sub-Query Variables

Use ALEPH_SUB_QUERY_BACKEND to pin a backend or bypass auto-detection; otherwise leave it unset for the default auto selection order.

Note: Some MCP clients don't reliably pass env vars from their config to the server process. If sub_query reports "API key not found" despite your client's MCP settings, add the exports to your shell profile:

• macOS / Linux: ~/.zshrc or ~/.bashrc
• Windows: System Environment Variables or $PROFILE in PowerShell

Then restart your terminal/client.

See docs/CONFIGURATION.md for the full list.

Workspace Root

The workspace root should be the directory containing your .git folder, pyproject.toml, package.json, etc.

Automatic detection: if you don't set --workspace-root, Aleph will:

1. Use ALEPH_WORKSPACE_ROOT if set
2. Prefer PWD (falls back to INIT_CWD) when present
3. Check if .git exists in that directory
4. If not, search parent directories until finding .git
5. Use that directory as the workspace root

Recommended: always set --workspace-root explicitly to avoid ambiguity. For multi-repo work, prefer --workspace-mode git and use absolute paths (or a broad workspace root).

Example Scenarios

Python Project

{
  "mcpServers": {
    "aleph": {
      "command": "aleph",
      "args": [
        "--workspace-root", "/Users/yourname/projects/my-python-app",
        "--enable-actions",
        "--tool-docs", "concise"
      ]
    }
  }
}

Monorepo (scoped to a subdirectory)

{
  "mcpServers": {
    "aleph": {
      "command": "aleph",
      "args": [
        "--workspace-root", "/Users/yourname/monorepo/packages/frontend",
        "--enable-actions",
        "--tool-docs", "concise"
      ]
    }
  }
}

Any Git Repo

{
  "mcpServers": {
    "aleph": {
      "command": "aleph",
      "args": [
        "--enable-actions",
        "--tool-docs", "concise",
        "--workspace-mode", "git"
      ]
    }
  }
}

Increased Limits

{
  "mcpServers": {
    "aleph": {
      "command": "aleph",
      "args": [
        "--workspace-root", "/path/to/project",
        "--enable-actions",
        "--tool-docs", "concise",
        "--timeout", "60",
        "--max-output", "100000",
        "--max-file-size", "5000000000",
        "--max-write-bytes", "500000000"
      ]
    }
  }
}

Security

Actions Mode

When you enable --enable-actions, you grant Aleph permission to:

Use --workspace-mode git to limit access to git repos, or --workspace-mode any to remove path restrictions.

Confirmation Mode

Use --require-confirmation for safer operation. When enabled, all action tools require confirm=true in the call:

{
  "args": [
    "--workspace-root", "/path/to/project",
    "--enable-actions",
    "--tool-docs", "concise",
    "--require-confirmation"
  ]
}

Troubleshooting

"Path escapes workspace root"

Cause: workspace root not set or incorrect.

Fix: add --workspace-root with the correct path, or use --workspace-mode git / --workspace-mode any for multi-repo access.

"Actions are disabled"

Cause: --enable-actions flag not set.

Fix: add --enable-actions to the args array in your MCP config.

MCP Server Not Starting

Check in order:

1. Aleph is installed: pip install "aleph-rlm[mcp]"
2. Entry point works: aleph --help
3. Python is in PATH: try the full path to python3
4. Workspace root path is correct
5. MCP client was restarted after config changes

sub_query Timed Out

Increase the timeout and/or reduce context size:

# Environment variable
export ALEPH_SUB_QUERY_TIMEOUT=120

# CLI flag
aleph --sub-query-timeout 120

Runtime (MCP tool):

mcp__aleph__configure(sub_query_timeout=120)

For very large context slices, chunk first (e.g., chunk(100000) + sub_query_batch).

sub_query Reports "API Key Not Found"

Cause: some MCP clients don't pass env vars reliably.

Fix: add credentials to your shell profile:

# macOS / Linux (~/.zshrc or ~/.bashrc)
export ALEPH_SUB_QUERY_API_KEY=sk-...
export ALEPH_SUB_QUERY_MODEL=your-model-name

# Windows (PowerShell $PROFILE)
$env:ALEPH_SUB_QUERY_API_KEY = "sk-..."
$env:ALEPH_SUB_QUERY_MODEL = "your-model-name"

Then restart your terminal/MCP client.

Related Documentation

Support

For MCP configuration issues, check:

1. Your MCP client documentation (Cursor, VS Code, Claude Desktop, Codex, etc.)
2. This configuration guide
3. docs/CONFIGURATION.md

For Aleph-specific bugs or feature requests, open an issue on GitHub.