# Access Confluent Cloud with the Managed MCP Servers Use the Confluent-managed MCP servers to explore environments and clusters, inspect topics and schemas, debug connectors, and query metrics in Confluent Cloud directly from your AI assistant. The servers connect through the Model Context Protocol (MCP). Most tools are read-only, so you can explore your Confluent resources without risk of modifying them. A few tools can restart a connector or update its configuration. These actions modify your Confluent Cloud resources. Access is governed by your existing Confluent Cloud permissions, so each server returns only the data your API key can access. ## Prerequisites To use the managed MCP servers, you need the following: - A Confluent Cloud account. - An API key for authentication. For details on which key types work with each server, see [Set up authentication](#ai-tools-managed-mcp-auth). - An MCP-compatible AI assistant, such as [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://www.cursor.com/), or VS Code with [GitHub Copilot](https://github.com/features/copilot). ## Global and regional MCP servers You connect to two managed MCP servers that serve different sets of tools: - The **global** MCP server handles organization-wide operations that aren’t tied to a specific region. It provides tools for discovering environments and clusters, debugging and managing connectors, and querying metrics. - The **regional** MCP server handles operations that require direct access to resources in a specific region. It provides tools for inspecting topics and schemas and reading messages. The URL includes your cloud provider, region, and organization ID. Configure both servers in your MCP client to get the full set of tools. If you only need environment and cluster discovery, the global server is sufficient on its own. Global server URL: ```text https://api.confluent.cloud/mcp/v1 ``` Regional server URL: ```text https://mcp...confluent.cloud/mcp/v1/organizations/ ``` Replace the following placeholders: - ``: your cloud region, for example `us-west-2` - ``: your cloud provider: `aws`, `gcp`, or `azure` - ``: your Confluent Cloud organization ID ## Available tools The managed MCP servers provide the following tools. ### Global server tools Use the global server to discover environments and clusters, inspect and debug connectors, and query operational metrics. #### Explore your environment Use the following tools to discover your Confluent Cloud environments and Apache Kafka® clusters. | Tool | Description | |---------------------|---------------------------------------------------------------------------------------------------------------------------------| | `list_environments` | List all Confluent Cloud environments you can access,
including environment IDs, names, and stream
governance packages. | | `read_environment` | Get details for a specific environment. | | `list_clusters` | List Kafka clusters in an environment, including
cluster type, cloud provider, region, and
availability. | | `read_cluster` | Get details and endpoints for a specific cluster. | #### Inspect and debug connectors Use the following tools to inspect connector health, review logs, and get AI-generated diagnostics for failing connectors. | Tool | Description | |-------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | `list_connectors` | List all connectors in a cluster with name, type,
and current status. | | `get_connector_config` | Get the full configuration for a connector,
including configuration parameters and task list. | | `get_connector_status` | Get runtime status and per-task status with error
traces. Possible statuses: PROVISIONING, RUNNING,
DEGRADED, FAILED, PAUSED, and DELETED. | | `get_connector_logs` | Fetch recent connector logs. Returns ERROR-level
logs by default, with optional WARN and INFO
levels. Maximum lookback is 72 hours. | | `get_connector_offsets` | Get partition and offset information showing the
connector’s consumption progress. | | `get_connector_metrics` | Fetch time-series metrics for a connector. | | `get_connector_error_summary` | Get an AI-generated summary of connector errors
extracted from task status and error traces. | | `get_connector_fix_recommendations` | Get AI-generated fix recommendations for a failing
connector. | #### Manage connectors Use the following tools to restart a connector and update its configuration. Unlike the other global server tools, these tools change your Confluent Cloud resources. | Tool | Description | |---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | `restart_connector` | Restart a connector and its tasks. | | `update_connector_config` | Update a connector’s configuration. Pass only the
fields you want to change; other fields are preserved.
You can’t remove a field by omitting it. | #### Query metrics Use the following tools to query throughput, consumer lag, and other operational metrics. | Tool | Description | |-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `list_metrics` | List available metric descriptors, including names,
types, and units. Supports resource types:
`kafka`, `connector`, `compute_pool`,
`ksql`, and `schema_registry`. | | `query_metrics` | Query time-series metric data for a cluster, such
as throughput or consumer lag. Supports custom time
intervals, granularity, and grouping by topic or
consumer group. | ### Regional server tools Use the regional server to work with Kafka topics and Schema Registry schemas in a specific cloud region. #### Inspect topics and schemas Use the following tools to list topics, view topic configuration, read sample messages, and get schema definitions. | Tool | Description | |--------------------------|---------------------------------------------------------------------------------------------------------------| | `list_kafka_topics` | List all topics in a cluster. | | `describe_kafka_topic` | Get topic configuration, including partition count
and replication factor. | | `consume_kafka_messages` | Read one to ten sample messages from a topic. You
can target a specific partition and offset. | | `list_schema_subjects` | List all schema subjects in Schema Registry, including subject
name, version, schema ID, and schema type. | | `read_schema_subject` | Get the full schema definition for a subject,
including content, version, and references. | ## Set up authentication The managed MCP servers use HTTP Basic authentication. The key type you use depends on which server you want to access. | Key type | Global server | Regional server | |------------------------------|-----------------|-------------------| | Global API key (recommended) | Supported | Supported | | Cloud API key | Supported | Not supported | | Flink API key | Not supported | Supported | A global API key provides access to both servers. A single global API key is the simplest way to configure both the global and regional servers. For more information, see [Global API Keys](../../security/authenticate/workload-identities/service-accounts/api-keys/overview.md#cloud-global-api-keys). A Cloud API key provides access to the global server only. Create a Cloud API key in the Confluent Cloud Console or with the Confluent CLI. A Flink API key provides access to the regional server only and is scoped to a specific cloud provider and region. Create a Flink API key in the Confluent Cloud Console or with the Confluent CLI. #### NOTE All key types are scoped to a single Confluent Cloud organization. If you belong to multiple organizations, you must either configure a separate MCP server connection for each organization or update your credentials when you switch organizations. The permissions attached to your credentials, not the server or endpoint itself, determine which Confluent Cloud resources you can access through MCP. For more information on key types, see [API Keys Overview](../../security/authenticate/workload-identities/service-accounts/api-keys/overview.md#api-keys-overview) and [Manage API Keys](../../security/authenticate/workload-identities/service-accounts/api-keys/manage-api-keys.md#manage-api-keys). You must Base64-encode your API key and secret for the `Authorization` header. To do so, run the following command: ```bash echo -n ':' | base64 ``` Use the resulting Base64 value when you configure your MCP client in the next section. MCP tools return only the resources that your API key has permission to access. Your access through MCP matches your access through the Confluent Cloud API and CLI, so the same roles that grant API access also grant access through MCP. ## Configure your MCP client After you create an API key and encode your credentials, configure your MCP client with the server URLs and authorization header. ### Configure Claude Code To add the global server, run the following command: ```bash claude mcp add --transport http \ confluent-mcp-global \ https://api.confluent.cloud/mcp/v1 \ --header "Authorization: Basic " ``` To add the regional server, run the following command: ```bash claude mcp add --transport http \ confluent-mcp-regional \ https://mcp...confluent.cloud/mcp/v1/organizations/ \ --header "Authorization: Basic " ``` Replace `` with the Base64 value from the previous section. ### Configure any MCP client Any MCP client that supports streamable HTTP transport can connect to the managed MCP servers. Configure your client with the following settings: Global server: - URL: `https://api.confluent.cloud/mcp/v1` - Transport: `http` - Header: `Authorization: Basic ` Regional server: - URL: `https://mcp...confluent.cloud/mcp/v1/organizations/` - Transport: `http` - Header: `Authorization: Basic ` ## Example prompts After you configure your MCP client, you can ask your AI assistant to work with your Confluent Cloud resources. The following examples show prompts organized by task. ### Explore your environment Use these prompts to discover your environments, clusters, and metrics: - “List my Confluent Cloud environments and clusters.” - “Show the details for cluster lkc-abc123.” - “What is the throughput for my cluster over the last six hours?” ### Inspect topics and schemas Use these prompts to explore topics, read messages, and view schemas: - “What topics exist in my cluster?” - “Describe the configuration for the orders topic.” - “Read the latest messages from the user-events topic.” - “Show the schema for the orders-value subject.” ### Debug connectors Use these prompts to investigate connector issues: - “List all connectors and show their current status.” - “Why is my S3 sink connector failing? Show the error logs.” - “Get fix recommendations for the postgres-source connector.” ## Limitations The managed MCP servers have the following limitations: - Most managed MCP server tools are read-only. You can restart a connector or update its configuration, but you can’t create or delete connectors, and you can’t create, change, or delete clusters or topics through MCP tools. - Connector error summaries and fix recommendations are generated by AI models. Because AI model outputs can vary between requests, review all AI-generated suggestions before taking action. - The regional server is available in regions where Confluent Cloud Flink is available, which covers most Confluent Cloud regions. - Rate limits match the underlying Confluent Cloud API limits. If you experience throttling, reduce the frequency of your requests. ## Private networking If your cluster uses private networking, you must use a private regional MCP server to access it. The private regional server is available in all regions where Confluent Cloud Flink is available. Before you can use a private regional MCP server, complete the following steps: - [File a support ticket](https://support.confluent.io/) to enable MCP access. Include your organization ID, environment ID, and cluster ID in the ticket. - Enable private networking with PrivateLink Gateway. The regional managed MCP server has no per-network or per-Confluent Cloud network routing endpoint, so use PrivateLink Gateway instead of a Confluent Cloud network (CCN) or an egress PrivateLink endpoint. For details, see [Enable private networking with PrivateLink Gateway](../../flink/operate-and-deploy/private-networking.md#flink-sql-enable-private-networking-pla). #### NOTE PrivateLink Gateway is the current name for this connectivity option, previously called PrivateLink Attachment (PLATT). It isn’t a legacy or deprecated option; it’s the only private connectivity option supported for the regional managed MCP server. The private regional server URL uses the following format: ```text https://mcp...private.confluent.cloud/mcp/v1/organizations/ ``` This URL uses the same placeholders as the public regional server URL, with `private` added to the hostname. #### NOTE **DNS resolution for the MCP hostname** The MCP hostname shares the same DNS domain as the Flink regional hostname (`flink...private.confluent.cloud`), differing only in the `mcp` service label. If you already configured private DNS resolution for Flink through the same PrivateLink Gateway, you don’t need extra configuration for MCP. If you need to configure DNS resolution, follow [Enable private networking with PrivateLink Gateway](../../flink/operate-and-deploy/private-networking.md#flink-sql-enable-private-networking-pla), using the DNS domain shown on your environment’s **Network management** page. This domain is different from the access-point domain shown during access point creation, for example, `.eastus2.azure.accesspoint.confluent.cloud`, which identifies the connection, not the DNS domain. If your MCP client runs outside the VPC or VNet with the private endpoint, use the same network path as Flink. Connect through a reverse proxy, VPN, or network peering. For details, see [Step 2: Connect to the network with Cloud Console or Confluent CLI](../../flink/operate-and-deploy/private-networking.md#flink-sql-enable-private-networking-connect-to-network). Whether a regional MCP server can reach a cluster depends on whether both the server and the cluster are public or private: - A public regional MCP server can’t access private clusters. - A private regional MCP server can access private clusters only in the same region, cloud provider, and environment as the private connection. Within that environment, the server can reach private clusters on a different network, such as a different CCN, than the one the private connection was set up for. See the warning below. - A private regional MCP server can access public clusters in the same region and cloud provider that your role-based access control (RBAC) permissions allow. If a public regional server tool tries to reach a private cluster, it returns the following error: `FORBIDDEN: private network access is not enabled for this kafka cluster`. #### WARNING **Cross-network access within an environment** A private regional MCP server never crosses environment boundaries. Within a single environment, network-level isolation between private clusters isn’t enforced. A private connection set up for one network can still reach private clusters on a different network in that same environment. Access to those clusters is still governed by your role-based access control (RBAC) permissions, but the network boundary itself doesn’t stop the request. If your security model depends on network-level segmentation between clusters in the same environment, treat this as a current limitation. Review your network topology and access configuration before enabling the feature. ## Troubleshooting If a tool returns no data, verify that your API key has the required permissions and that the resource exists in the specified environment or cluster. If you receive a 404 or “no such host” error when connecting to the regional server, verify that your endpoint URL is correct. The URL must include the `` path segment and the region must match a region where Confluent Cloud Flink is available. If you receive a 401 or FORBIDDEN error, verify the following: - Your API key is valid and hasn’t expired. - You are using the correct key type for the server. Cloud API keys work only with the global server, and Flink API keys work only with the regional server. - Your API key belongs to the same organization as the `` in the regional server URL. This is a common issue when you have multiple organizations. - You aren’t using a resource-scoped API key. Keys scoped to a specific resource, such as a cluster or Schema Registry, aren’t supported. - You encoded your credentials correctly as Base64. You can track MCP tool calls in the Confluent Cloud audit log. Each tool call is logged with a method name prefixed by `mcp.tools/call.`, followed by the tool name, and attributed to the authenticated principal. ## Related content - [Use AI Tools with Confluent Cloud](overview.md#ai-tools-overview) - [Use the Open-Source MCP Server](open-source-mcp-server.md#ai-tools-oss-mcp) - [Build with Agent Skills](agent-skills.md#ai-tools-agent-skills)