> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote MCP in Cloud

> Description of the remote MCP functionality in ClickHouse Cloud

Not all users interact with ClickHouse through the Cloud console.
For example, many developers work directly from their preferred code editors, CLI agents, or connect to the database via custom setups, while others rely on general-purpose AI assistants such as Anthropic Claude for most of their explorations.
These users and the agentic workloads acting on their behalf need a way to securely access and query ClickHouse Cloud without complex setups or custom infrastructure.

The remote MCP server capability in ClickHouse Cloud addresses this by exposing a standard interface that external agents can use to retrieve analytical context.
MCP, or Model Context Protocol, is a standard for structured data access by AI applications powered by LLMs.
With this integration, external agents can list databases and tables, inspect schemas, and run scoped, read-only SELECT queries.
Authentication is handled via OAuth 2.0 or a [ClickHouse Cloud API key](https://clickhouse.com/docs/cloud/manage/openapi.md). The server is fully managed on ClickHouse Cloud, so no setup or maintenance is required.

This makes it easier for agentic tools to plug into ClickHouse and retrieve the data they need, whether for analysis, summarization, code generation, or exploration.

## Remote MCP server vs open-source MCP server

ClickHouse offers two MCP servers.

| | Remote MCP server (Cloud) | Open-source MCP server |
| - | - | - |
| **Source** | Fully managed by ClickHouse Cloud | [mcp-clickhouse](https://github.com/ClickHouse/mcp-clickhouse) on GitHub |
| **Transport** | Streamable HTTP (`https://mcp.clickhouse.cloud/mcp`) | Local stdio |
| **Works with** | ClickHouse Cloud and Managed Postgres services | Any ClickHouse instance (self-hosted or Cloud) |
| **Authentication** | OAuth 2.0 with your Cloud credentials, or a ClickHouse Cloud API key | Environment variables |
| **Tools** | Tools for querying, schema exploration, service management, backups, ClickPipes, billing, and Postgres monitoring | 3 tools: `run_select_query`, `list_databases`, `list_tables` |
| **Setup** | Zero installation. Point your MCP client at the endpoint and authenticate. | Install and run the server locally |

The remote MCP server provides the richest integration with ClickHouse Cloud, including service management, backup monitoring, ClickPipe visibility, and billing data, with no infrastructure to manage.
For self-hosted ClickHouse instances, see the [open-source MCP server guides](https://clickhouse.com/docs/guides/use-cases/ai-ml/MCP/index.md).

## Enabling the remote MCP server

The remote MCP server must be enabled per service before it can accept connections.
In the ClickHouse Cloud console, open your service, click the **Connect** button, select **MCP**, and enable it.
For ClickHouse services, enabling or disabling the remote MCP server requires the `control-plane:service:manage-mcp` permission (see [Console roles and permissions](https://clickhouse.com/docs/products/cloud/reference/security/console-roles.md#console-permissions)).
For Managed Postgres services, open the service's **Connect** panel and turn on **Enable Model Context Protocol**. Read replicas inherit the parent database's MCP setting.
For detailed steps with screenshots, see the [setup guide](https://clickhouse.com/docs/products/cloud/features/ai-ml/mcp/remote-mcp.md#enable-remote-mcp-server).

## Endpoint

Once enabled, the remote MCP server is available at:

```text theme={null}
https://mcp.clickhouse.cloud/mcp
```

## Authentication

The remote MCP server supports two authentication methods:

* **OAuth 2.0**: Recommended for interactive clients. When an MCP client connects for the first time, it opens a browser window for the user to sign in with their ClickHouse Cloud credentials. Access is scoped to the organizations and services the authenticated user has permission to access.
* **ClickHouse Cloud API key**: Intended for remote, headless, and automated environments where a browser-based OAuth flow is not practical. Send the API key ID and secret using HTTP Basic authentication:

  ```text theme={null}
  Authorization: Basic base64(<key_id>:<key_secret>)
  ```

API-key access is scoped by the roles, permissions, and expiration configured for the key. Use a dedicated, least-privilege key and inject it through a secret-management system. Base64 encoding does not encrypt the credentials, so do not commit the encoded value to source control or expose it in logs.

For an example of configuring an MCP client in a headless environment, see [Authenticate from a headless environment](https://clickhouse.com/docs/products/cloud/features/ai-ml/mcp/remote-mcp.md#headless-mcp-client-authentication).

## Safety

All tools exposed by the remote MCP server are **read-only**. Each tool is annotated with `readOnlyHint: true` in its MCP metadata. No tool can modify data, alter service configuration, or perform any destructive operation.

## Available tools

The remote MCP server provides tools in the following categories. Tool availability depends on the authentication method and enabled features.

### Query and schema exploration

These tools allow agents to discover what data is available and run analytical queries.

| Tool | Description | Parameters |
| - | - | - |
| `run_select_query` | Execute a read-only SELECT query against a ClickHouse service. | `query`, a valid ClickHouse SQL SELECT query; `serviceId` |
| `list_databases` | List all databases available in a ClickHouse service. | `serviceId` |
| `list_tables` | List all tables in a database, including column definitions. | `serviceId`; `database`; optionally `like` or `notLike` (SQL LIKE patterns to filter table names) |

### Managed Postgres

These tools query and monitor Managed Postgres services. Use `get_organizations` to find the `organizationId`, then `get_services_list` to find a service whose `serviceType` is `postgres` and use its `id` as `serviceId`.

| Tool | Description | Parameters |
| - | - | - |
| `run_postgres_select_query` | Execute a read-only SQL query against a Postgres service. Requires OAuth authentication; unavailable with ClickHouse Cloud API keys. | `organizationId`; `serviceId`; `query`; optionally `database` (default: `postgres`) and `timeoutSeconds` (1–3600, default: 300) |
| `list_postgres_slow_query_patterns` | List slow query patterns with aggregate latency, call count, rows, CPU, I/O, WAL, and error metrics. Durations are in microseconds. | `organizationId`; `serviceId`; `fromDate`; `toDate`; optionally `limit` (1–500, default: 20), `offset`, `sortBy`, `sortOrder`, `dbName`, `dbUser`, `dbOperation`, and `app` |
| `get_postgres_slow_query_pattern_details` | Return up to 10 recent executions of a query pattern from the last 24 hours, plus aggregate metrics when available. | `organizationId`; `serviceId`; `queryId`; `dbName`; `dbUser`; `dbOperation`; optionally `app` |
| `get_postgres_metrics` | Return time-series metrics for CPU, memory, disk, network, connections, cache hit ratio, transactions, and waits. Each metric includes its unit and labeled series. | `organizationId`; `serviceId`; `fromDate`; `toDate`; optionally `bucketSizeSeconds` (positive integer; automatically selected when omitted) |

For `fromDate` and `toDate`, use UTC timestamps with millisecond precision, such as `2026-11-03T00:00:00.000Z`. The start is inclusive. The end is inclusive at minute granularity for slow query patterns and exclusive for metrics.

To inspect a slow query pattern, pass its `queryId`, `dbName`, `dbUser`, `dbOperation`, and `app` from `list_postgres_slow_query_patterns` to `get_postgres_slow_query_pattern_details`. Preserve an empty `app` string for queries without an `application_name`; omitting `app` includes all applications.

### Organizations

| Tool | Description | Parameters |
| - | - | - |
| `get_organizations` | Retrieve all ClickHouse Cloud organizations accessible to the authenticated user. | None |
| `get_organization_details` | Return details of a single organization. | `organizationId` |

### Services

| Tool | Description | Parameters |
| - | - | - |
| `get_services_list` | List ClickHouse and Managed Postgres services in an organization, with a `serviceType` field identifying each kind. | `organizationId` |
| `get_service_details` | Return details of a ClickHouse or Managed Postgres service, detecting its type automatically. | `organizationId`; `serviceId` |

### Backups

| Tool | Description | Parameters |
| - | - | - |
| `list_service_backups` | List all backups for a service, most recent first. | `organizationId`; `serviceId` |
| `get_service_backup_details` | Return details of a single backup. | `organizationId`; `serviceId`; `backupId` |
| `get_service_backup_configuration` | Return the backup configuration for a service (schedule and retention settings). | `organizationId`; `serviceId` |

### ClickPipes

| Tool | Description | Parameters |
| - | - | - |
| `list_clickpipes` | List all ClickPipes configured for a service. | `organizationId`; `serviceId` |
| `get_clickpipe` | Return details of a specific ClickPipe. | `organizationId`; `serviceId`; `clickPipeId` |

### Billing

| Tool | Description | Parameters |
| - | - | - |
| `get_organization_cost` | Retrieve billing and usage cost data for an organization. Returns a grand total and daily per-entity cost records. | `organizationId`; optionally `from_date` and `to_date` (YYYY-MM-DD, max 31-day range) |

## Getting started

See the [setup guide](https://clickhouse.com/docs/products/cloud/features/ai-ml/mcp/remote-mcp.md) for step-by-step instructions on enabling the remote MCP server and connecting it to an MCP client.
