Confluent Developer Marketplace Get started
  1. Home
  2. Cloud
  3. AI and ML in Confluent Cloud
  4. Use AI Tools with Confluent

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, run and debug Flink SQL statements, 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, update a connector’s configuration, or create or delete a Flink SQL statement. These actions change your Confluent Cloud resources.

Access is governed by your existing Confluent Cloud permissions, so each server returns only the data your credentials can access.

Prerequisites

To use the managed MCP servers, you need the following:

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, reading messages, and managing and debugging Flink SQL statements. 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:

https://api.confluent.cloud/mcp/v1

Regional server URL:

https://mcp.<region>.<cloud>.confluent.cloud/mcp/v1/organizations/<org_id>

Replace the following placeholders:

  • <region>: your cloud region, for example us-west-2

  • <cloud>: your cloud provider: aws, gcp, or azure

  • <org_id>: your Confluent Cloud organization ID

Available tools

The managed MCP servers provide the following tools.

Before a tool changes your Confluent Cloud resources, the managed MCP servers ask your MCP client to confirm the action with you. Your client, not the servers, decides whether to show you this confirmation request.

Warning

Check your MCP client’s auto-approval settings before you use tools that change your Confluent Cloud resources, such as restart_connector, create_flink_statement, and delete_flink_statement. If your client approves tool calls automatically, it might also approve the confirmation request without showing it to you. Consider turning off auto-approval for these tools, especially for tools that delete resources, because you can’t undo a deletion.

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 for clusters and Flink SQL statements.

Tool

Description

list_metrics

List available metric descriptors, including names, types, and units. Supports resource types: kafka, connector, compute_pool, flink_statement, 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.

get_flink_statement_metrics

Fetch time-series metrics for a Flink SQL statement, such as throughput, backpressure, parallelism, state size, watermarks, and lag. To find available metric names, run list_metrics with the flink_statement resource type.

Regional server tools

Use the regional server to work with Kafka topics, Schema Registry schemas, and Flink SQL statements in a specific cloud region.

Inspect topics and schemas

Use the following tools to list topics, view topic configuration, read sample messages, get schema definitions, and describe Flink SQL table schemas.

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.

describe_flink_table_schema

Get a Flink SQL table’s schema, including columns, types, primary key, watermarks, distribution, and connector options. Use it to write SQL that matches your actual columns.

Supported authentication types

You can authenticate with the managed MCP servers in the following ways:

  • Confluent Cloud account sign-in (OAuth): Your MCP client opens a browser so you can sign in. The servers act with your own permissions. When you work with the servers interactively, use this method.

  • API key authentication: Your MCP client sends the API key with HTTP Basic authentication. Use this method for service accounts and automated workflows.

Confluent Cloud account sign-in (OAuth)

When you sign in with your Confluent Cloud account, you don’t need to create or manage an API key. Your MCP client opens a browser to the Confluent Cloud sign-in page. Sign in the same way you sign in to the Confluent Cloud Console: with your email and password, with Google or GitHub, or with your organization’s single sign-on (SSO).

The servers then act as your user account. MCP tools return only the resources that your role bindings allow, the same as through the Confluent Cloud API and CLI.

Your client refreshes the session in the background. When the session ends, your client prompts you to sign in again. Signing out of the Confluent Cloud Console also ends your MCP sessions.

Your MCP client needs a client ID that Confluent registered for it. Use the client ID for your client from the following table. The same client ID works for every managed MCP server, including the Real-Time Context Engine server.

MCP client

Client ID

Claude Code

claude-cli

Claude Desktop

claude-desktop

claude.ai

claude-ai

VS Code, including GitHub Copilot

vscode-desktop

Cursor

cursor-desktop

IBM Bob

bob-desktop

API key authentication

With an API key, 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.

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 and Manage API Keys.

You must Base64-encode your API key and secret for the Authorization header. To do so, run the following command:

echo -n '<api_key>:<api_secret>' | 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 choose an authentication method, configure your MCP client with the server URLs and your client ID or your authorization header.

Configure Claude Code

To configure Claude Code, use one of the following authentication methods:

To add the global server, run the following command:

claude mcp add --transport http --client-id claude-cli \
  confluent-mcp-global \
  "https://api.confluent.cloud/mcp/v1"

Each sign-in session belongs to one Confluent Cloud organization. If you belong to more than one organization, the global server uses the organization that you last signed in to. To choose a different organization, add the org_resource_id query parameter to the global server URL. For example:

claude mcp add --transport http --client-id claude-cli \
  confluent-mcp-global \
  "https://api.confluent.cloud/mcp/v1?org_resource_id=<org_id>"

Keep the quotes around the URL so that your shell doesn’t interpret the ? character.

To switch organizations later, change the org_resource_id value in the server URL. Then clear the server’s authentication in Claude Code. Sign in again.

To add the regional server, run the following command:

claude mcp add --transport http --client-id claude-cli \
  confluent-mcp-regional \
  "https://mcp.<region>.<cloud>.confluent.cloud/mcp/v1/organizations/<org_id>"

If Claude Code is already running, restart it so that the new servers appear.

To sign in to each server, complete the following steps:

  1. In Claude Code, run /mcp.

  2. Select the server.

  3. Select Authenticate.

  4. In the browser window that opens, sign in to Confluent Cloud.

  5. Return to Claude Code.

The server shows as connected. Repeat these steps for the other server.

To add the global server, run the following command:

claude mcp add --transport http \
  confluent-mcp-global \
  https://api.confluent.cloud/mcp/v1 \
  --header "Authorization: Basic <encoded_credentials>"

To add the regional server, run the following command:

claude mcp add --transport http \
  confluent-mcp-regional \
  https://mcp.<region>.<cloud>.confluent.cloud/mcp/v1/organizations/<org_id> \
  --header "Authorization: Basic <encoded_credentials>"

Replace <encoded_credentials> with the Base64 value from API key authentication.

Configure any MCP client

Any MCP client that supports streamable HTTP transport can connect to the managed MCP servers with an API key. To sign in with your Confluent Cloud account, use a client with a registered client ID. For the list of clients, see Confluent Cloud account sign-in (OAuth).

Configure your client with the following settings for your authentication method.

Global server:

  • URL: https://api.confluent.cloud/mcp/v1

  • Transport: http

  • OAuth client ID: the client ID for your client

Regional server:

  • URL: https://mcp.<region>.<cloud>.confluent.cloud/mcp/v1/organizations/<org_id>

  • Transport: http

  • OAuth client ID: the client ID for your client

If you belong to more than one organization, add ?org_resource_id=<org_id> to the global server URL to choose one. Otherwise, the global server uses the organization that you last signed in to.

Don’t set an Authorization header. Your client starts the sign-in flow when it first connects to each server.

Global server:

  • URL: https://api.confluent.cloud/mcp/v1

  • Transport: http

  • Header: Authorization: Basic <encoded_credentials>

Regional server:

  • URL: https://mcp.<region>.<cloud>.confluent.cloud/mcp/v1/organizations/<org_id>

  • Transport: http

  • Header: Authorization: Basic <encoded_credentials>

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, update a connector’s configuration, and create or delete a Flink SQL statement. 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 for Apache 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.

  • To sign in with your Confluent Cloud account, you must use an MCP client with a client ID that Confluent registered. The servers don’t support dynamic client registration, so other clients must use an API key. To ask Confluent to register another client, file a support ticket that includes the client’s name and version.

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 for Apache Flink is available.

Before you can use a private regional MCP server, complete the following steps:

  • File a support ticket 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.

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:

https://mcp.<region>.<cloud>.private.confluent.cloud/mcp/v1/organizations/<org_id>

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.<region>.<cloud>.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, 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, <access_point_id>.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.

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

The following sections help you resolve common problems with the managed MCP servers, such as connection errors, API key errors, and sign-in errors. The last section describes how to track MCP tool calls in the audit log.

Tool returns no data

If a tool returns no data, verify that your user account or API key has the required permissions. Also verify that the resource exists in the specified environment or cluster.

Regional server connection errors

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 <org_id> path segment and the region must match a region where Confluent Cloud for Apache Flink is available.

API key errors

If you use an API key and 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 <org_id> 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.

Client fails to connect before the browser opens

If your client fails to connect before a browser opens, the error might mention dynamic client registration or an authentication failure. In that case, your client isn’t sending a client ID. Add the client ID for your client. For the list of client IDs, see Confluent Cloud account sign-in (OAuth).

Browser doesn’t return to your client after sign-in

After you sign in, the browser might never return to your client, or it might show that it can’t connect to localhost or 127.0.0.1. In either case, your client can’t receive the sign-in response. Check whether a firewall, VPN, or remote session blocks local connections on your computer.

Client ID isn’t registered

If your browser shows the message unable to retrieve client by id, your client uses a client ID that isn’t registered. Use the client ID for your client. For the list of client IDs, see Confluent Cloud account sign-in (OAuth). If your client isn’t in the list, file a support ticket to request registration.

Client ID doesn’t match your client

If your browser shows the following message, your client uses the client ID of a different client:

The requested redirect_uri is missing in the client configuration.

Use the client ID that matches your client.

Account isn’t a member of the organization

If your browser shows the following message, you signed in with an account that isn’t a member of the organization in the server URL:

You are not a member of Confluent Cloud organization <org-id>. Ask an admin of that organization to invite you, or use an MCP server URL for an organization you belong to.

To fix the error, sign out of Confluent Cloud in your browser. Then do one of the following:

  • Sign in again with an account that belongs to the organization.

  • Change the server URL to an organization that you belong to, and then sign in again.

Audit logs for MCP tool calls

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