integration.md

Horizon MCP Integration

Recommended Command

Start the built-in MCP server from the Horizon repository root:

uv run horizon-mcp

If you need a Python module fallback:

uv run python -m src.mcp.server

Two Setup Modes

Option A: Client Config With Explicit cwd

Some MCP clients need a fixed working directory in their config. In that case, the absolute path is only used in the client-side cwd field, not in Horizon's code.

Example:

{
  "mcpServers": {
    "horizon": {
      "command": "uv",
      "args": ["run", "horizon-mcp"],
      "cwd": "/absolute/path/to/Horizon"
    }
  }
}

Restart the client after saving the config.

Option B: Local Start Without Any Path In Config

If your workflow allows you to start the MCP server manually, no absolute path is needed at all:

cd /absolute/path/to/Horizon
uv run horizon-mcp

This is the cleanest way to avoid path values in client configuration.

Secret Files

Instead of exporting environment variables manually, you can place a JSON file in one of these locations:

• .cursor/mcp.secrets.json
• .cursor/mcp.secrets.local.json
• config/mcp.secrets.json
• config/mcp.secrets.local.json
• <horizon_path>/data/mcp.secrets.json
• <horizon_path>/data/mcp-secrets.json

Supported formats:

{
  "OPENAI_API_KEY": "sk-xxxx",
  "ANTHROPIC_API_KEY": "sk-ant-xxxx",
  "GOOGLE_API_KEY": "xxxx",
  "GITHUB_TOKEN": "ghp_xxxx"
}

{
  "env": {
    "OPENAI_API_KEY": "sk-xxxx",
    "ANTHROPIC_API_KEY": "sk-ant-xxxx",
    "GOOGLE_API_KEY": "xxxx",
    "GITHUB_TOKEN": "ghp_xxxx"
  }
}

You can also point to a custom secrets file with:

{
  "HORIZON_MCP_SECRETS_PATH": "/absolute/path/to/mcp.secrets.json"
}

Smoke Check

Run the local smoke check from the repository root:

uv run python scripts/check_mcp.py

It verifies module import, path resolution, config loading, and metrics access.