Configure or update the Kafka cluster connection details at runtime.

Use this tool when:

• No Kafka cluster is configured yet and other tools return a 'not configured' error.

• The user wants to switch to a different Kafka cluster.

• The user provides new credentials or bootstrap servers.

The new connection takes effect immediately — no server restart required. All existing clients are reset and will reconnect on the next tool call.

Args: bootstrap_servers: Kafka broker address(es), e.g. 'bootstrap-clstr-XXXXX.kafka.us-chicago-1.oci.oraclecloud.com:9092' security_protocol: PLAINTEXT, SSL, SASL_PLAINTEXT, or SASL_SSL (default: SASL_SSL) sasl_mechanism: SCRAM-SHA-512, SCRAM-SHA-256, or PLAIN (required for SASL_*) sasl_username: SASL username (required for SASL_*) sasl_password: SASL password (required for SASL_*) ssl_ca_location: Path to CA certificate bundle for TLS verification. If not set and security_protocol is SASL_SSL or SSL, the system default CA bundle is used. persist: If True, save the connection details to ~/.oci/kafka-mcp-connection.env so they survive server restarts. Load them with: source ~/.oci/kafka-mcp-connection.env

Show the current Kafka connection configuration.

Returns connection details with the password masked. Use this to:

• Check whether a cluster is already configured before calling other tools.

• Verify which cluster the server is connected to.

• Confirm security settings before troubleshooting connectivity issues.

If 'configured' is false, call oci_kafka_configure_connection first.

Get Kafka cluster health status including broker list, controller info, and topic count.

Returns cluster ID, controller ID, broker count and details, and total topic count. Use this to verify cluster connectivity and check overall cluster health.

Get Kafka cluster configuration settings.

Returns broker-level configuration including log settings, replication defaults, and other cluster parameters. Use this to inspect current cluster settings.

Create a new OCI Streaming with Apache Kafka cluster.

Requires --allow-writes. This is a HIGH RISK operation that requires confirmation. The operation is asynchronous — use oci_kafka_get_work_request to track progress.

Args: display_name: Human-readable name for the cluster. compartment_id: OCI compartment OCID where the cluster will be created. subnet_id: OCI subnet OCID for the cluster's private network. broker_count: Number of broker nodes (default: 3). kafka_version: Kafka version to deploy (default: 3.6.0). cluster_type: PRODUCTION or DEVELOPMENT (default: PRODUCTION). ocpu_count: OCPUs per broker node (default: 2). storage_size_in_gbs: Storage per broker in GB (default: 50). cluster_config_id: Optional OCID of a cluster configuration to apply.

Update an OCI Kafka cluster's display name, tags, or applied configuration.

Requires --allow-writes. The operation is asynchronous — use oci_kafka_get_work_request to track progress.

Args: cluster_id: OCI Kafka cluster OCID (ocid1.kafkacluster.*). display_name: New display name for the cluster. cluster_config_id: OCID of the cluster configuration to apply. cluster_config_version: Specific version number of the config to apply. freeform_tags: Free-form tags as a dict of string key-value pairs.

Scale an OCI Kafka cluster to a different broker count.

Requires --allow-writes. This is a HIGH RISK operation that requires confirmation. The operation is asynchronous — use oci_kafka_get_work_request to track progress.

Args: cluster_id: OCI Kafka cluster OCID to scale. broker_count: Target number of broker nodes.

Delete an OCI Kafka cluster permanently.

Requires --allow-writes. This is a HIGH RISK operation that requires confirmation. The operation is asynchronous — use oci_kafka_get_work_request to track progress. ALL DATA ON THE CLUSTER WILL BE PERMANENTLY LOST.

Args: cluster_id: OCI Kafka cluster OCID to delete (ocid1.kafkacluster.*).

Move an OCI Kafka cluster to a different OCI compartment.

Requires --allow-writes. This is a HIGH RISK operation that requires confirmation. Moving a cluster changes which IAM policies and users can access it.

Args: cluster_id: OCI Kafka cluster OCID to move. target_compartment_id: Target OCI compartment OCID.

Enable the superuser for an OCI Kafka cluster.

Requires --allow-writes. The superuser has full administrative access to all Kafka resources. Use sparingly and with a time limit.

Args: cluster_id: OCI Kafka cluster OCID. duration_in_hours: Optional duration (hours) to keep superuser enabled. If not set, superuser stays enabled until explicitly disabled.

Disable the superuser for an OCI Kafka cluster.

Requires --allow-writes. Use this after completing administrative tasks to restore least-privilege access.

Args: cluster_id: OCI Kafka cluster OCID.

Create a new OCI Kafka cluster configuration.

Requires --allow-writes. A cluster configuration is a named, versioned container for Kafka broker settings. After creation, use oci_kafka_update_cluster to apply it to a cluster.

Args: display_name: Human-readable name for the configuration. compartment_id: OCI compartment OCID where the config will live. freeform_tags: Optional free-form string key-value tags.

Get detailed information about an OCI Kafka cluster configuration.

Returns the config metadata and its latest version. Use oci_kafka_list_cluster_config_versions to see all versions.

Args: cluster_config_id: OCI cluster config OCID (ocid1.kafkaclusterconfig.*).

List OCI Kafka cluster configurations in a compartment.

If compartment_id is not provided, falls back to the OCI_COMPARTMENT_ID environment variable or the tenancy OCID from ~/.oci/config.

Args: compartment_id: OCI compartment OCID to search. If omitted, uses the tenancy OCID from the OCI config file as the default scope.

Update an OCI Kafka cluster configuration's name or tags.

Requires --allow-writes. Updating metadata does not create a new version. The operation is asynchronous — use oci_kafka_get_work_request to track it.

Args: cluster_config_id: OCI cluster config OCID (ocid1.kafkaclusterconfig.*). display_name: New display name for the configuration. freeform_tags: Updated free-form string key-value tags.

Delete an OCI Kafka cluster configuration permanently.

Requires --allow-writes. This is a HIGH RISK operation that requires confirmation. All versions of the configuration will be deleted. Clusters referencing this config should be updated before deletion.

Args: cluster_config_id: OCI cluster config OCID to delete (ocid1.kafkaclusterconfig.*).

Move an OCI Kafka cluster configuration to a different compartment.

Requires --allow-writes. Moving a config changes which IAM policies and users can access it.

Args: cluster_config_id: OCI cluster config OCID to move. target_compartment_id: Target OCI compartment OCID.

Get a specific version of an OCI Kafka cluster configuration.

Args: cluster_config_id: OCI cluster config OCID (ocid1.kafkaclusterconfig.*). version_number: The integer version number to retrieve.

List all versions of an OCI Kafka cluster configuration.

Configurations are versioned — each update creates a new version. Use this to see the version history and identify which version to apply or roll back to.

Args: cluster_config_id: OCI cluster config OCID (ocid1.kafkaclusterconfig.*).

Delete a specific version of an OCI Kafka cluster configuration.

Requires --allow-writes. Deleting a version is irreversible. Do not delete a version that is currently applied to a cluster.

Args: cluster_config_id: OCI cluster config OCID (ocid1.kafkaclusterconfig.*). version_number: The integer version number to delete.

List all topics in the Kafka cluster.

Returns the total topic count and a list of topics with their partition counts. Use this to get an overview of all topics in the cluster.

Get detailed information about a specific Kafka topic.

Args: topic_name: Name of the topic to describe.

Returns partition details (leader, replicas, ISR), and non-default configuration settings. Use this to inspect a topic's health and config.

Create a new Kafka topic.

Requires --allow-writes to be enabled.

Args: topic_name: Name for the new topic. num_partitions: Number of partitions (default: 6). replication_factor: Replication factor (default: 3).

Returns the creation status and topic details.

Update configuration settings for a Kafka topic.

Requires --allow-writes to be enabled.

Args: topic_name: Name of the topic to update. configs: Dictionary of config key-value pairs to set (e.g., {"retention.ms": "604800000", "cleanup.policy": "compact"}).

Returns the update status and the configs that were changed.

Delete a Kafka topic. THIS IS A DESTRUCTIVE OPERATION.

Requires --allow-writes to be enabled. This is a HIGH RISK operation that requires confirmation.

Args: topic_name: Name of the topic to delete.

Returns the deletion status.

List all consumer groups in the Kafka cluster.

Returns the total group count and a list of consumer groups with their state and type information.

Get detailed information about a consumer group.

Args: group_id: The consumer group ID to describe.

Returns the group state, coordinator, partition assignor, and member details including their topic-partition assignments.

Get consumer lag for a consumer group across all assigned partitions.

Args: group_id: The consumer group ID to check lag for.

Returns total lag, and per-partition details including committed offset, end offset, and lag. Use this to diagnose slow consumers or processing bottlenecks.

Reset consumer group offsets for a topic. THIS IS A DESTRUCTIVE OPERATION.

The consumer group must have no active members (EMPTY state). Requires --allow-writes to be enabled. This is a HIGH RISK operation that requires confirmation.

Args: group_id: The consumer group ID to reset offsets for. topic_name: The topic to reset offsets for. strategy: Reset strategy — 'earliest' (beginning), 'latest' (end), or a specific integer offset. partition: Optional specific partition number. If omitted, resets all partitions.

Returns the reset status and new offset positions for each partition.

Delete a consumer group. THIS IS A DESTRUCTIVE OPERATION.

The consumer group must have no active members (EMPTY state). Requires --allow-writes to be enabled. This is a HIGH RISK operation that requires confirmation.

Args: group_id: The consumer group ID to delete.

Returns the deletion status.

Detect partition imbalance across brokers.

Checks if partitions are evenly distributed across brokers (as leaders). A skew ratio > 1.5 indicates significant imbalance that may cause performance degradation.

Args: topic_name: Optional topic to check. If not provided, checks all topics.

Returns skew ratio, per-broker partition counts, and a recommendation.

Detect partitions where the in-sync replica (ISR) count is less than the replica count.

Under-replicated partitions indicate potential data durability risks. This can be caused by broker failures, network issues, or disk problems.

Returns the total partition count, under-replicated count, and details of each affected partition including which replicas are missing from ISR.

Analyze the cluster and recommend scaling actions.

Collects broker count, topic/partition distribution, replication health, and partition skew to produce a structured scaling recommendation.

This tool gathers data only — the LLM agent should interpret the findings and present human-readable recommendations to the user.

Returns a diagnostic report with:

• Current cluster capacity (brokers, partitions, topics)

• Partition distribution analysis (skew ratio per broker)

• Replication health (under-replicated partitions)

• Broker utilization metrics (leader partitions and replica load)

• Specific scaling recommendations with severity levels

Analyze consumer lag and identify potential root causes.

Collects consumer group state, per-partition lag, topic partition details, and cluster health to diagnose why a consumer group may be falling behind.

This tool gathers data only — the LLM agent should interpret the findings and present a root cause analysis to the user.

Args: group_id: The consumer group ID to analyze.

Returns a diagnostic report with:

• Consumer group state and member count

• Per-partition lag breakdown with severity classification

• Topic health (partition count, replication status)

• Cluster health context (broker count, controller status)

• Potential root causes ranked by likelihood

Get OCI control plane metadata for a Kafka cluster.

Returns the cluster OCID, display name, lifecycle state, Kafka version, broker shape (node count, OCPUs, storage), bootstrap URLs, compartment, and tags.

Args: cluster_id: OCI Kafka cluster OCID (ocid1.kafkacluster.*). Defaults to OCI_CLUSTER_ID environment variable if not provided.

Use this to answer questions like "What is the cluster OCID?", "What is the cluster name?", or "What state is the cluster in?".

If you don't have a cluster_id, first call oci_kafka_list_oci_clusters to discover available clusters and their OCIDs, or ask the user to provide the cluster OCID.

List all Kafka clusters in an OCI compartment.

Returns the count of clusters and a list with each cluster's OCID, display name, lifecycle state, Kafka version, broker shape, and creation time.

Args: compartment_id: OCI compartment OCID. Defaults to OCI_COMPARTMENT_ID env var, then to the tenancy OCID from the OCI config file (~/.oci/config).

Use this to discover available clusters, check their lifecycle states, or find a cluster OCID before calling oci_kafka_get_oci_cluster_info.

If no compartment_id is provided, the tool automatically uses the tenancy OCID from the OCI config file as the default compartment.

Get the status and details of an asynchronous OCI work request.

Use this after any async operation (create/update/delete cluster, enable superuser, etc.) to track progress. Poll until status is SUCCEEDED or FAILED.

Args: work_request_id: Work request OCID returned by the triggering operation.

List OCI work requests, optionally filtered by compartment or resource.

Use resource_id to find all operations on a specific cluster or config. If neither filter is provided, uses the tenancy OCID from ~/.oci/config.

Args: compartment_id: OCI compartment OCID to filter work requests. resource_id: OCI resource OCID to find operations affecting that resource (e.g., a cluster OCID to see all work requests for that cluster).

Cancel an in-progress OCI work request.

Requires --allow-writes. Only in-progress requests can be cancelled. Already-completed or failed requests cannot be cancelled.

Args: work_request_id: Work request OCID to cancel.

Get error details from a failed OCI work request.

Call this when oci_kafka_get_work_request shows status FAILED to get the specific error codes and messages explaining the failure.

Args: work_request_id: Work request OCID that failed.

Get log entries from an OCI work request.

Returns timestamped log messages from the work request execution. Useful for understanding the sequence of steps in a long-running operation.

Args: work_request_id: Work request OCID to retrieve logs for.

List available broker node shapes for OCI Kafka cluster provisioning.

Returns available shapes with their OCPU and memory specs. Use this before oci_kafka_create_cluster to choose an appropriate broker shape.

Args: compartment_id: Optional OCI compartment OCID to scope the shape list.