MCP Integration¶

MCP Zen of Languages is designed as an MCP server first. The server exposes zen analysis as tools that AI agents can call — analyze code, generate reports, and produce remediation prompts, all from within your editor. This is the recommended way to use the project.

Start the server¶

mcp-zen-of-languages-server

Compatibility aliases remain available: mcp-zen-of-languages and zen-mcp-server

The server communicates via stdin/stdout using the MCP protocol. It doesn't serve HTTP — MCP clients connect to it as a subprocess.

The server enables advanced FastMCP features: centralized middleware (logging, timing, rate limiting, response caching/limiting, duplicate-call suppression), OpenTelemetry-compatible spans, lifecycle hooks, and paginated listing (list_page_size=100) for scalable client discovery.

When your client supports version targeting, use analyze_zen_violations and generate_prompts v2.0 for stricter request-quality guardrails; v1.0 remains available for compatibility.

Naming guide (important)¶

VS Code configuration¶

Use one-click install or add config manually.

mcp-zen-of-languages-cli init --mcp-target vscode can generate .vscode/mcp.json for you (zen init --mcp-target vscode is a compatibility alias); keep the server key as zen-of-languages.

{
  "servers": {
    "zen-of-languages": {
      "command": "uvx",
      "args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
    }
  }
}

{
  "servers": {
    "zen-of-languages": {
      "command": "uvx",
      "args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
    }
  }
}

{
  "servers": {
    "zen-of-languages": {
      "command": "uvx",
      "args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"],
      "env": {
        "ZEN_CONFIG_PATH": "${input:zenConfigPath}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "zenConfigPath",
      "description": "Path to zen-config.yaml",
      "default": "${workspaceFolder}/zen-config.yaml"
    }
  ]
}

{
  "servers": {
    "zen-of-languages": {
      "command": "uvx",
      "args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
    }
  }
}

Once configured, MCP-compatible clients (VS Code with Copilot, Codex, Claude Desktop, etc.) can invoke zen tools directly.

Quick verification checklist¶

1. Run mcp-zen-of-languages-cli --help to confirm the CLI is installed.
2. Run uvx --from mcp-zen-of-languages mcp-zen-of-languages-server (or your configured command) to confirm server startup.
3. In VS Code, run MCP: List Servers and confirm zen-of-languages appears.

Claude Desktop configuration¶

Add to your claude_desktop_config.json (usually in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "zen-of-languages": {
      "command": "uvx",
      "args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"],
      "env": {
        "ZEN_CONFIG_PATH": "/path/to/your/zen-config.yaml"
      }
    }
  }
}

Replace /path/to/your/zen-config.yaml with the absolute path to your config file, or omit the env section to use default auto-discovery.

Claude Code integration¶

Install the server using the Claude Code CLI:

claude mcp add zen-of-languages -- uvx --from mcp-zen-of-languages mcp-zen-of-languages-server

This automatically adds the server to Claude Code's MCP configuration.

Codex configuration¶

Add this to ~/.codex/config.toml:

[mcp_servers."zen-of-languages"]
command = "uvx"
args = ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
enabled = true

Codex reads MCP entries from the global config file rather than a workspace .json file. mcp-zen-of-languages-cli init --mcp-target codex can append this block for you (the shorter zen init --mcp-target codex is available as a compatibility alias). If you want to pin a repo-specific config file, add env = { ZEN_CONFIG_PATH = "/absolute/path/to/zen-config.yaml" } under the same table.

GitHub Copilot-compatible JSON configs¶

mcp-zen-of-languages-cli init can also scaffold Copilot-compatible JSON files:

• mcp-zen-of-languages-cli init --mcp-target copilot-local writes .github/mcp.json
• mcp-zen-of-languages-cli init --mcp-target copilot-global writes ~/.copilot/mcp-config.json

Legacy users can also run the shorter zen init --mcp-target ... alias, which behaves the same but is kept primarily for compatibility.

Cursor/Windsurf integration¶

For Cursor and Windsurf, add to your MCP configuration file:

Edit .cursor/mcp.json in your project root:

```json
{
  "mcpServers": {
    "zen-of-languages": {
      "command": "uvx",
      "args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"],
      "env": {
        "ZEN_CONFIG_PATH": "${workspaceFolder}/zen-config.yaml"
      }
    }
  }
}
```

Edit .windsurf/mcp.json in your project root:

```json
{
  "mcpServers": {
    "zen-of-languages": {
      "command": "uvx",
      "args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"],
      "env": {
        "ZEN_CONFIG_PATH": "${workspaceFolder}/zen-config.yaml"
      }
    }
  }
}
```

Available MCP tools¶

The server exposes 13 MCP tools, plus 3 resources and 1 prompt.

For full parameter and return schemas, see the MCP Tools Reference.

Perspective-aware MCP requests¶

The current runtime supports five public perspectives:

• all — full rule-first result
• zen — rule-level result without dogma-analysis payloads
• dogma — dogma-focused result with universal dogma analysis preserved
• testing — test-family view resolved from real file paths
• projection — explicit family projection driven by project_as

Repository or report target¶

Use generate_report when you want a perspective-aware result over files that already exist on disk:

{
  "tool": "generate_report",
  "arguments": {
    "target_path": "tests",
    "perspective": "testing",
    "include_prompts": true
  }
}

Explicit projection target¶

Projection requests must include project_as:

{
  "tool": "generate_report",
  "arguments": {
    "target_path": "src/frontend",
    "language": "react",
    "perspective": "projection",
    "project_as": "nextjs"
  }
}

Snippet-tool caveat¶

analyze_zen_violations and generate_prompts accept perspective, but testing is only meaningful when the runtime can inspect a real file path. For test-family filtering, use a file- or directory-based surface such as generate_report or the CLI.

Workflow example¶

1. Open a Python file in VS Code
2. Ask Copilot: "Run zen analysis on this file"
3. The agent calls analyze_zen_violations via MCP
4. You get back violations with severity scores and fix suggestions
5. Ask: "Fix the highest-severity violation" — the agent uses the remediation context to apply changes

Troubleshooting¶

Server not showing up in VS Code¶

1. Verify uvx is installed:

uvx --version

If not found, install uv: pip install uv

1. Check VS Code MCP extension is enabled:
2. Open Command Palette (Cmd/Ctrl+Shift+P)
3. Search for "MCP: List Servers"

4. Verify "zen-of-languages" appears

5. Test server manually:

uvx --from mcp-zen-of-languages mcp-zen-of-languages-server

You should see JSON output indicating the server is ready.

1. Check logs:
2. VS Code: Open "Output" panel → Select "MCP" from dropdown
3. Look for connection errors or startup failures

Python version conflicts¶

If you see errors about Python 3.12+ requirement:

# Check your Python version
python --version

# Use a specific Python version with uvx
uvx --python 3.12 --from mcp-zen-of-languages mcp-zen-of-languages-server

Config file not discovered¶

The server looks for zen-config.yaml in:

1. Current working directory
2. Nearest parent directory containing pyproject.toml

Override with environment variable:

{
  "env": {
    "ZEN_CONFIG_PATH": "/absolute/path/to/zen-config.yaml"
  }
}

Debugging with verbose output¶

Enable debug logging:

{
  "env": {
    "FASTMCP_DEBUG": "true",
    "FASTMCP_LOG_LEVEL": "DEBUG"
  }
}

This logs detailed MCP protocol messages and tool invocations.

Common issues¶

Next steps¶

• CLI Reference — Full CLI command documentation
• Prompt Generation — How remediation prompts work
• Configuration — Customize which detectors run