# MCP Server

> Expose your chmonitor instance as a Model Context Protocol server so AI assistants can query your ClickHouse cluster directly.

| | |
|---|---|
| **Routes** | `/mcp` (UI info page) |
| **Feature id** | `mcp` |
| **Default access** | Closed (401) — requires `CHM_API_KEY_SECRET`, `CLERK_SECRET_KEY`, or `CHM_MCP_PUBLIC=true` |
| **System tables** | None directly — the MCP server wraps the same tools available to the rest of the dashboard |
| **ClickHouse grants** | Inherits grants of the configured `CLICKHOUSE_USER` |

## What it does

chmonitor exposes a remote MCP (Model Context Protocol) endpoint at `/api/mcp`. External AI tools — Claude Desktop, Cursor, or any MCP-compatible client — can connect and run tools against your ClickHouse cluster without direct database access.

The MCP server is stateless and uses Streamable HTTP transport. Each request is independently authenticated.

Tools available via MCP include schema exploration, query execution, metrics, health checks, and more. The `/mcp` page in the dashboard UI shows the connection URL and instructions for configuring an MCP client.

See [MCP Server reference](/reference/mcp-server) for the full tool list and protocol details.

## Pages

| Page | Route | What it shows | System tables |
|---|---|---|---|
| MCP Info | `/mcp` | Connection URL, setup instructions, tool list | — |

## Permissions & access

:::caution[Secure by default]
The MCP endpoint (`/api/mcp`) returns **401 Unauthorized** by default. It only opens when you explicitly configure at least one of:

- **`CHM_API_KEY_SECRET`** — API key auth (recommended). See [API keys](/authentication/api-keys).
- **`CLERK_SECRET_KEY`** — Clerk OAuth token introspection. See [Clerk authentication](/authentication/clerk).
- **`CHM_MCP_PUBLIC=true`** — explicit opt-in for trusted private networks. A warning is logged on every request.

Without one of these, every request — including from Claude Desktop, Cursor, and other MCP clients — is rejected with `401`.
:::

The MCP endpoint (`/api/mcp`) is **closed by default**. Anonymous requests receive a `401` response unless at least one of the following is true:

- `CHM_API_KEY_SECRET` is set (API key auth — recommended for production)
- `CLERK_SECRET_KEY` is set (Clerk OAuth)
- `CHM_MCP_PUBLIC=true` is set (explicit opt-in for trusted private networks; a warning is logged on every request)

**Production setup — API key auth:**

```bash
CHM_API_KEY_SECRET=<random-secret-min-32-chars>
```

Issue a token:

```bash
curl -X POST https://your-chmonitor.example.com/api/v1/auth/api-key \
  -H "Authorization: Bearer $CHM_API_KEY_SECRET"
## returns {"token":"chm_..."}
```

Pass the token in MCP client requests:

```
Authorization: Bearer chm_...
```

**Production setup — Clerk OAuth (MCP OAuth flow):**

When `CHM_AUTH_PROVIDER=clerk`, the `/api/mcp` endpoint also accepts Clerk OAuth bearer tokens. Clerk acts as the auth server; chmonitor verifies the token via REST introspection using `CLERK_SECRET_KEY`. No additional MCP-specific configuration needed.

Disable the MCP feature (removes it from the nav and blocks `/api/mcp`):

```bash
CHM_FEATURE_MCP_ENABLED=false
```

Config file:

```toml
[features.mcp]
enabled = true
```

## Configuration

| Variable | Description |
|---|---|
| `CHM_API_KEY_SECRET` | Enables API key authentication for all `/api/v1/*` routes including `/api/mcp`. Required for production use without Clerk. |
| `CLERK_SECRET_KEY` | Enables Clerk OAuth token verification. Used for Clerk OAuth token introspection. |
| `CHM_MCP_PUBLIC` | Set to `true` to allow anonymous access when no auth scheme is configured. Only appropriate for trusted private networks. A warning is logged on every request when this is active. |
| `CHM_AUTH_PROVIDER` | `none` (default), `clerk`, or `proxy`. Controls how sessions are verified. |

The MCP endpoint is secure by default: it returns `401` when no auth is configured, unless `CHM_MCP_PUBLIC=true` is explicitly set.

## Notes & limitations

- The MCP server is stateless. It does not maintain session state between requests.
- All queries executed via MCP run as the ClickHouse user configured in `CLICKHOUSE_USER`. Grant that user only the permissions it needs.
- Tool availability via MCP mirrors the dashboard's query capabilities. MCP does not expose write operations by default; control tools (`AGENT_ENABLE_CONTROL_TOOLS=true`) would be needed for kill/optimize actions, and even then those are not exposed via MCP.
- The `/mcp` UI page is purely informational. The protocol endpoint is `/api/mcp`.

## Related

- [MCP Server reference](/reference/mcp-server)
- [API keys](/authentication/api-keys)
- [Authentication](/authentication)
- [Feature permissions](/advanced/feature-permissions)