Confluent Cloud AI Interoperability Layer (mcp-confluent-gateway)

This repository houses the implementation of an MCP server designed explicitly to bridge AI assistants (like Claude Desktop or Goose CLI) with the comprehensive capabilities exposed by the Confluent Cloud REST APIs. It translates natural language instructions into concrete API calls for managing critical Kafka infrastructure elements, data contracts (schemas), and real-time data processing jobs (Flink SQL).

Operational Demos

Agent Workbench (Goose CLI)

Desktop Companion (Claude Desktop)

Confluent Cloud AI Interoperability Layer
Operational Demos
- Agent Workbench (Goose CLI)
- Desktop Companion (Claude Desktop)
Navigation Index
User Implementation Handbook
Development & Maintenance Manual

User Implementation Handbook

Initial Deployment Steps

Establish Configuration File: Replicate the template .env file structure (detailed subsequently) into a new, root-level file named .env.
Parameter Population: Input all necessary credentials and cluster identifiers for your Confluent Cloud environment. Consult the System Setup & Parameters section for variable specifics.
Node.js Environment Setup (If absent):
We highly advocate for NVM for robust Node.js version management.
Install and select the required Node.js version:

bash nvm install 22 nvm use 22

System Setup & Parameters

Define your environment specifics in the root .env file:

Illustrative .env File Schema

properties # .env file BOOTSTRAP_SERVERS="pkc-v12gj.us-east4.gcp.confluent.cloud:9092" KAFKA_API_KEY="..." KAFKA_API_SECRET="..." KAFKA_REST_ENDPOINT="https://pkc-v12gj.us-east4.gcp.confluent.cloud:443" KAFKA_CLUSTER_ID="" KAFKA_ENV_ID="env-..." FLINK_ENV_ID="env-..." FLINK_ORG_ID="" FLINK_REST_ENDPOINT="https://flink.us-east4.gcp.confluent.cloud" FLINK_ENV_NAME="" FLINK_DATABASE_NAME="" FLINK_API_KEY="..." FLINK_API_SECRET="..." FLINK_COMPUTE_POOL_ID="lfcp-..." TABLEFLOW_API_KEY="..." TABLEFLOW_API_SECRET="..." CONFLUENT_CLOUD_API_KEY="..." CONFLUENT_CLOUD_API_SECRET="..." CONFLUENT_CLOUD_REST_ENDPOINT="https://api.confluent.cloud" SCHEMA_REGISTRY_API_KEY="..." SCHEMA_REGISTRY_API_SECRET="..." SCHEMA_REGISTRY_ENDPOINT="https://psrc-zv01y.northamerica-northeast2.gcp.confluent.cloud"

Preconditions for Tableflow Operations

To successfully invoke Tableflow commands for data ecosystem interaction and resource manipulation (e.g., accessing external storage like AWS S3 or metadata catalogs like AWS Glue), specific Identity and Access Management (IAM) authorizations and configurations are mandatory.

It is essential to provision the required roles and corresponding policies within your cloud provider (e.g., AWS) and ensure they are correctly cross-referenced within the Confluent Cloud interface. This step guarantees that the underlying Flink SQL engine, which executes Tableflow queries, possesses the necessary delegation to act on your behalf.

Please consult the official Confluent Cloud documentation for comprehensive guidance on establishing these permissions and integrating custom storage/Glue catalog mappings:

Confluent Cloud Tableflow Quick Start with Custom Storage & Glue: https://docs.confluent.io/cloud/current/topics/tableflow/get-started/quick-start-custom-storage-glue.html

Satisfying these prerequisites eliminates potential authorization failures when the mcp-server attempts to provision or govern Tableflow-enabled data structures.

Runtime Variable Reference Guide

Variable	Role Description	Default Setting	Mandatory
HTTP_HOST	Network interface address for HTTP communication binding. (`0.0.0.0` signifies all interfaces). (Text)	"0.0.0.0"	Yes
HTTP_MCP_ENDPOINT_PATH	Designated URI path for HTTP-based MCP traffic (e.g., '/mcp'). (Text)	"/mcp"	Yes
HTTP_PORT	Numerical port assignment for the HTTP communication channel (Value >= 0).	8080	Yes
LOG_LEVEL	Verbosity setting for application logs (trace, debug, info, warn, error, fatal) (Effects)	"info"	Yes
SSE_MCP_ENDPOINT_PATH	URI path for establishing Server-Sent Events (SSE) links (e.g., '/sse', '/events'). (Text)	"/sse"	Yes
SSE_MCP_MESSAGE_ENDPOINT_PATH	URI path for receiving transcribed messages via SSE (e.g., '/messages', '/events/messages'). (Text)	"/messages"	Yes
BOOTSTRAP_SERVERS	A delimited string of Kafka broker endpoints required for initial cluster handshake. (Text)		No
CONFLUENT_CLOUD_API_KEY	Primary credential (key) for global Confluent Cloud administrative operations across the organization. (Text, Min Length 1)		No
CONFLUENT_CLOUD_API_SECRET	Primary credential (secret) corresponding to the API Key for comprehensive Confluent Cloud platform administration. (Text, Min Length 1)		No
CONFLUENT_CLOUD_REST_ENDPOINT	Base URL resolving to the default Confluent Cloud REST services gateway.		No
FLINK_API_KEY	Authentication credential for accessing Confluent Cloud Flink capabilities, including compute pool administration and SQL execution. (Text, Min Length 1)		No
FLINK_API_SECRET	Authentication token paired with FLINK_API_KEY for secure Flink service access. (Text, Min Length 1)		No
FLINK_COMPUTE_POOL_ID	Unique identifier for the designated Flink compute resource; must adhere to 'lfcp-' prefixing. (Text)		No
FLINK_DATABASE_NAME	Name mapping to the target Kafka cluster, used as the reference database context in Flink SQL procedures. (Text, Min Length 1)		No
FLINK_ENV_ID	Unique identifier for the Flink operational environment; must adhere to 'env-' prefixing. (Text)		No
FLINK_ENV_NAME	Human-readable identifier for the Flink environment, used for display context. (Text, Min Length 1)		No
FLINK_ORG_ID	The organizational identifier within Confluent Cloud relevant to Flink resource governance. (Text, Min Length 1)		No
FLINK_REST_ENDPOINT	The base URL pointing to the Confluent Cloud Flink REST endpoint suite, used for statement and pool management. (Text)		No
KAFKA_API_KEY	The username credential necessary for initiating secure connectivity to the Kafka broker(s). (Text, Min Length 1)		No
KAFKA_API_SECRET	The password credential paired with KAFKA_API_KEY for authenticated Kafka cluster ingress. (Text, Min Length 1)		No
KAFKA_CLUSTER_ID	The definitive identifier for the Kafka cluster within the Confluent Cloud topology. (Text, Min Length 1)		No
KAFKA_ENV_ID	The environmental identifier for the Kafka cluster; must adhere to 'env-' prefixing. (Text)		No
KAFKA_REST_ENDPOINT	The primary REST API ingress point for Kafka cluster administrative tasks. (Text)		No
SCHEMA_REGISTRY_API_KEY	Authentication key for services managing and validating data contracts within the Schema Registry. (Text, Min Length 1)		No
SCHEMA_REGISTRY_API_SECRET	Authentication secret paired with SCHEMA_REGISTRY_API_KEY for secure Schema Registry interaction. (Text, Min Length 1)		No
SCHEMA_REGISTRY_ENDPOINT	The URL endpoint accessing the Schema Registry services for data schema lifecycle management. (Text)		No
TABLEFLOW_API_KEY	Credential key required to interact with Confluent Cloud Tableflow capabilities. (Text, Min Length 1)		No
TABLEFLOW_API_SECRET	Credential secret paired with TABLEFLOW_API_KEY for secure Tableflow service engagement. (Text, Min Length 1)		No

Execution Procedures

This gateway server is architected for seamless integration with diverse MCP consumers, such as Claude Desktop or the Goose CLI suite. While the exact invocation differs by client, the general operational flow remains consistent:

Initiate the Server: The server can be launched via two primary methods:
From Local Source: Adhere to the instructions in the Development & Maintenance Manual to build and execute locally. This typically involves dependency resolution (npm install) followed by compilation (npm run build or npm run dev).
Via npx Utility: Execute the server directly using npx, bypassing a local build step:

bash npx -y @confluentinc/mcp-confluent -e /path/to/confluent-mcp-server/.env
Client Connection Setup: Each consuming client (e.g., Claude, Goose) mandates its own configuration mechanism for specifying the MCP server's network address and any requisite access tokens. Configure your client to target the address where this gateway is operational (typically localhost on a specified port).
Activate the MCP Client: Upon starting the consuming agent, it will automatically instantiate a local execution of this MCP server. This instance then acts as the intermediary, handling all Confluent Cloud API interactions on the client's behalf.
Conversational Control: Once the client has established its link, utilize the client's interface to issue commands regarding Confluent Cloud entities. These commands are relayed to the MCP gateway for execution against the relevant Confluent services.

Configuring Desktop Companion

Refer to the official documentation here for detailed instructions on installing Claude Desktop and integrating MCP gateways.

To bind this Confluent gateway with Claude Desktop:

Access Configuration Interface
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Modify Configuration Structure
Edit the JSON file and incorporate the setup using one of the subsequent formats:

Method 1: Launching from Compiled Source

{ "mcpServers": { "confluent": { "command": "node", "args": [ "/path/to/confluent-mcp-server/dist/index.js", "--env-file", "/path/to/confluent-mcp-server/.env" ] } } }

Method 2: Launching via npx

{ "mcpServers": { "confluent": { "command": "npx", "args": [ "-y" "@confluentinc/mcp-confluent", "-e", "/path/to/confluent-mcp-server/.env" ] } } }

Ensure that /path/to/confluent-mcp-server/ reflects the actual location of the installed gateway code.

Relaunch Desktop Companion
Terminate and restart Claude Desktop for the new configuration to be initialized.
The MCP server instance will self-activate upon the desktop application's startup, ready for Confluent operations.

Configuring Agent Workbench

Consult this resource for comprehensive Goose CLI installation instructions.

Post-installation, follow these integration steps:

Execute Configuration Utility:

bash goose configure

Follow Interactive Prompts:
Select the option to Add extension
Designate the type as Command-line Extension
Input mcp-confluent as the unique extension identifier
Specify the launch command:

Method 1: Launching from Compiled Source

bash node /path/to/confluent-mcp-server/dist/index.js --env-file /path/to/confluent-mcp-server/.env

Method 2: Launching via npx

bash npx -y @confluentinc/mcp-confluent -e /path/to/confluent-mcp-server/.env

Replace /path/to/confluent-mcp-server/ with the directory path where this gateway package resides.

Configuring Gemini Agent Interface

For in-depth context regarding Gemini CLI extensions and MCP server integration, consult the official documentation:

Procedure for enabling mcp-confluent within the Gemini CLI environment:

Install Gemini CLI: If not yet installed, obtain the Gemini CLI package from the official GitHub repository.
Register the mcp-confluent Extension:

bash gemini extensions install https://github.com/confluentinc/mcp-confluent

Alternatively, if cloning locally, navigate to the project root and execute:

gemini extensions install .

This action registers the server with the CLI and sets up the necessary storage directory, typically at ~/.gemini/extensions/mcp-confluent.
Supply Runtime Credentials: The extension strictly requires Confluent Cloud configuration secrets, expected within a .env file.
- Verify your root project directory contains a correctly provisioned .env file (see System Setup & Parameters).
- Copy this file into the extension's isolated directory so Gemini CLI can locate it (the extension framework anticipates the .env file at ${extensionPath}${pathSeparator}.env; review the variables documentation for specifics):
bash cp .env ~/.gemini/extensions/mcp-confluent/.env
Verification and Utilization: Confirm tool availability by querying the registered toolset:

bash gemini -l

Or equivalently: gemini extensions list

Example interaction invoking a data management tool:

bash

gemini ....

🟢 mcp-confluent (from mcp-confluent) - Active (24 tools available) ....

Engage Tool: 1 MCP server active (Ctrl+T to toggle communication) ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ > retrieve all active topic identifiers │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ list-topics (mcp-confluent MCP Server) {} │ │ │ │ Kafka topics discovered: │ │ products_summarized,products,topic_8,products_summarized_with_embeddings,elastic_minimized,user_message_related_products,user_message_embeddin │ │ gs,dlq-lcc-d3738o,user_message,elastic │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ✦ Acknowledged. The discovered topic identifiers are: products_summarized, products, topic_8, products_summarized_with_embeddings, elastic_minimized, user_message_related_products, user_message_embeddings, dlq-lcc-d3738o, user_message, and elastic.

Gateway CLI Control Interface

The MCP server exposes a fine-grained Command Line Interface (CLI) for advanced configuration, enabling precise control over environment loading, active communication channels, and the specific toolset permitted for use.

Fundamental Invocation

To view the full spectrum of available CLI arguments and access the built-in help documentation:

bash npx @confluentinc/mcp-confluent --help

Help Output View

bash Usage: mcp-confluent [options] Confluent MCP Server - Model Context Protocol implementation for Confluent Cloud Options: -V, --version output the version number -e, --env-file Load environment variables from file -k, --kafka-config-file Path to a properties file for configuring kafka clients -t, --transport Transport types (comma-separated list) (choices: "http", "sse", "stdio", default: "stdio") --allow-tools Comma-separated list of tool names to allow. If provided, takes precedence over --allow-tools-file. Allow-list is applied before block-list. --block-tools Comma-separated list of tool names to block. If provided, takes precedence over --block-tools-file. Block-list is applied after allow-list. --allow-tools-file File with tool names to allow (one per line). Used only if --allow-tools is not provided. Allow-list is applied before block-list. --block-tools-file File with tool names to block (one per line). Used only if --block-tools is not provided. Block-list is applied after allow-list. --list-tools Print the final set of enabled tool names (with descriptions) after allow/block filtering and exit. Does not start the server. --disable-confluent-cloud-tools Disable all tools that require Confluent Cloud REST APIs (cloud-only tools). -h, --help display help for command

Scenario: Activating All Communication Pathways

Ensuring the server listens across HTTP, SSE, and standard I/O channels simultaneously:

bash npx @confluentinc/mcp-confluent -e .env --transport http,sse,stdio

Transport Activation Log

... {"level":"info","time":"2025-05-14T17:03:02.883Z","pid":47959,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Launching transports: http, sse, stdio"} {"level":"info","time":"2025-05-14T17:03:02.971Z","pid":47959,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"HTTP pathways successfully mapped"} {"level":"info","time":"2025-05-14T17:03:02.972Z","pid":47959,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"SSE pathways successfully mapped"} {"level":"info","time":"2025-05-14T17:03:02.972Z","pid":47959,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"STDIO channel established"} {"level":"info","time":"2025-05-14T17:03:03.012Z","pid":47959,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Server active on http://[::1]:3000"} {"level":"info","time":"2025-05-14T17:03:03.013Z","pid":47959,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Server active on http://127.0.0.1:3000"} {"level":"info","time":"2025-05-14T17:03:03.013Z","pid":47959,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"All communication pathways are operational"}

Scenario: Restricting Toolset via Inclusion List

Only permit the produce-message and consume-messages capabilities, disabling all others:

bash npx @confluentinc/mcp-confluent -e .env --allow-tools produce-message,consume-messages

Inclusion Restriction Log

{"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-topics deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-topics deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-topics deactivated by allow/block filtering logic"} {"level":"info","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool produce-message activated"} {"level":"info","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool consume-messages activated"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-flink-statements deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-flink-statement deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-flink-statement deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-flink-statements deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-connectors deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-connector deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-connector deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-connector deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool search-topics-by-tag deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool search-topics-by-name deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-topic-tags deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-tag deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool remove-tag-from-entity deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool add-tags-to-topic deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-tags deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool alter-topic-config deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-clusters deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-environments deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-environment deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-schemas deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool get-topic-config deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool create-tableflow-topic deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool list-tableflow-regions deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool list-tableflow-topics deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool read-tableflow-topic deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool update-tableflow-topic deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool delete-tableflow-topic deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool create-tableflow-catalog-integration deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool list-tableflow-catalog-integrations deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool read-tableflow-catalog-integration deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool update-tableflow-catalog-integration deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool delete-tableflow-catalog-integration deactivated by allow/block filtering logic"} {"level":"info","time":"2025-05-14T16:52:34.924Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Initiating transports: stdio on localhost:3000"} {"level":"info","time":"2025-05-14T16:52:34.924Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"STDIO channel established"} {"level":"info","time":"2025-05-14T16:52:34.924Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"All communication pathways are operational"}

Scenario: Disabling Specific Functionality

Excluding capabilities tied directly to Confluent Cloud's native REST services (e.g., focusing on local Kafka interactions or predefined tools):

bash npx @confluentinc/mcp-confluent -e .env --disable-confluent-cloud-tools

Scenario: Utilizing External Tool Manifests

Employing configuration files to manage inclusion/exclusion lists, which is ideal for complex, version-controlled policies:

bash npx -y @confluentinc/mcp-confluent -e .env --allow-tools-file allow.txt --block-tools-file block.txt

External Manifest Log (Example of mixed result)

{"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-topics activated"} {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-topics activated"} {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-topics activated"} {"level":"warn","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool produce-message deactivated by allow/block filtering logic"} {"level":"warn","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool consume-messages deactivated by allow/block filtering logic"} {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-flink-statements activated"} ... (Truncated for brevity) ... {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"All communication pathways are operational"}

Scenario: Exhaustive Tool Manifest Listing

Print the fully resolved tool definitions without launching the server daemon:

bash npx -y @confluentinc/mcp-confluent --list-tools

Tool Manifest Output

text add-tags-to-topic: Assign existing tags to Kafka topics in Confluent Cloud. alter-topic-config: Alter topic configuration in Confluent Cloud. consume-messages: Consumes messages from one or more Kafka topics. Supports automatic deserialization of Schema Registry encoded messag... create-connector: Create a new connector. Returns the new connector information if successful. create-flink-statement: Make a request to create a statement. create-topic-tags: Create new tag definitions in Confluent Cloud. create-topics: Create one or more Kafka topics. delete-connector: Delete an existing connector. Returns success message if deletion was successful. delete-flink-statements: Make a request to delete a statement. delete-tag: Delete a tag definition from Confluent Cloud. delete-topics: Delete the topic with the given names. get-topic-config: Retrieve configuration details for a specific Kafka topic. list-clusters: Get all clusters in the Confluent Cloud environment list-connectors: Retrieve a list of "names" of the active connectors. You can then make a read request for a specific connector by name. list-environments: Get all environments in Confluent Cloud with pagination support list-flink-statements: Retrieve a sorted, filtered, paginated list of all statements. list-schemas: List all schemas in the Schema Registry. list-tags: Retrieve all tags with definitions from Confluent Cloud Schema Registry. list-topics: List all topics in the Kafka cluster. produce-message: Produce records to a Kafka topic. Supports Confluent Schema Registry serialization (AVRO, JSON, PROTOBUF) for both ke... read-connector: Get information about the connector. read-environment: Get details of a specific environment by ID read-flink-statement: Make a request to read a statement and its results remove-tag-from-entity: Remove tag from an entity in Confluent Cloud. search-topics-by-name: List all topics in the Kafka cluster matching the specified name. search-topics-by-tag: List all topics in the Kafka cluster with the specified tag. create-tableflow-topic: Make a request to create a tableflow topic. list-tableflow-regions: Retrieve a sorted, filtered, paginated list of all tableflow regions. list-tableflow-topics: Retrieve a sorted, filtered, paginated list of all tableflow topics. read-tableflow-topic: Make a request to read a tableflow topic. update-tableflow-topic: Make a request to update a tableflow topic. delete-tableflow-topic: Make a request to delete a tableflow topic. create-tableflow-catalog-integration: Make a request to create a catalog integration. list-tableflow-catalog-integrations: Retrieve a sorted, filtered, paginated list of all catalog integrations. read-tableflow-catalog-integration: Make a request to read a catalog integration. update-tableflow-catalog-integration: Make a request to update a catalog integration. delete-tableflow-catalog-integration: Make a request to delete a tableflow catalog integration.

Implementation Note: The inclusion list takes precedence; if both are specified, the exclusion list is evaluated secondarily against the already filtered set.

Development & Maintenance Manual

Source Code Organization

sh / ├── src/ # Core source assets │ ├── confluent/ # Confluent API interaction modules │ │ └── tools/ # Individual operational tool handlers │ ├── mcp/ # MCP protocol handling and transport abstraction layers │ │ └── transports/ │ └── ... # Supporting server logic, utilities, configurations ├── dist/ # Transpiled output artifacts ├── openapi.json # OpenAPI specification file defining Confluent Cloud capabilities ├── .env # Configuration template (User must populate this file) ├── README.md # Documentation content (this file) └── package.json # Node.js metadata and dependency manifest

Build and Launch Sequence

Dependency Acquisition:

bash npm install
Iterative Development Mode (Live Reloading):

bash npm run dev

This initiates TypeScript compilation to JavaScript and watches the src/ directory for automatic rebuilds upon file modification.
Production Compilation (Single Build Cycle):

bash npm run build
Server Execution:

bash npm run start

Containerization Strategy (Docker)

Prerequisite Software

Ensure you have the following foundational tools installed locally:

Docker Desktop (or separate Docker Engine and Docker Compose installations): https://www.docker.com/products/docker-desktop

Environment Variable Configuration within Docker Contexts

The server requires external secrets and configuration parameters, typically managed via the root .env file. Alternatively, these variables can be directly injected within the docker-compose.yml definition.

Building and Launching via Native Docker Image

Navigate to the Repository Root: Use your terminal to enter the directory containing the Dockerfile.

bash cd /path/to/repo/mcp-confluent
Build the Deployment Image: This command tags the resulting artifact as mcp-server.

bash docker build -t mcp-server .
Execute the Container: Key flags explained:
- --rm: Ensures ephemeral container instances are purged upon termination.
- -i: Maintains an open STDIN channel (enabling stdio transport by default).
- -d: Launches the process in detached (background) mode.
- -p 3000:3000: Maps host port 3000 to container port 3000. Modify based on HTTP_PORT setting if required.
bash docker run --rm -i -d -p 3000:3000 mcp-server

(Optional) To specifically mandate HTTP communication, override the default transport:

bash docker run --rm -d -p 3000:3000 mcp-server -t http

Orchestration with Docker Compose

Navigate to Project Root: Ensure your terminal is in the directory containing both the Dockerfile and docker-compose.yml.

bash cd /path/to/repo/mcp-confluent
Build and Start Orchestration: Docker Compose handles the image creation (if necessary) and service startup.

bash docker compose up --build

The --build flag forces a rebuild. Omit it for faster subsequent startups if source code is unchanged.

The running server endpoint will resolve to http://localhost:3000 (subject to the HTTP_PORT environment variable).
Halting the System To stop the active MCP server and decommission associated containers, use Ctrl+C in the active docker compose up terminal.

Alternatively, use this command in a new terminal session from the project directory:

bash docker compose down

This cleanly stops and removes all created containers and networks.

Validation Procedures

MCP Diagnostic Tool (Inspector)

For robust testing and debugging of the MCP server, utilize the dedicated MCP Inspector:

bash

Ensure the project is built (npm run build or npm run dev)

npx @modelcontextprotocol/inspector node $PATH_TO_PROJECT/dist/index.js --env-file $PATH_TO_PROJECT/.env

Integrating Novel Capabilities

To extend the server's functionality with a new tool:

Introduce a new identifier within the ToolName enumeration.
Register the new implementation within the ToolFactory class's handler map.
Develop the specific logic in a dedicated file, ensuring the class inherits from BaseToolHandler:
1. Override the core execution logic within the handle method.
2. Define the tool's metadata via the getToolConfig method.
Integrate the new handler into the collective enabledTools set defined in index.ts.

Schema Type Generation Process

To synchronize TypeScript interfaces with the OpenAPI specification (addressing known version issues):

bash

Note: The --empty-objects-unknown flag is critical for stability with complex 'allOf' constructs in recent OpenAPI specs.

npx openapi-typescript ./openapi.json -o ./src/confluent/openapi-schema.d.ts --empty-objects-unknown

Contribution Guidelines

We welcome bug reports and constructive feedback via Github Issues. Detailed specifications for submitting code changes or documentation enhancements are located in CONTRIBUTING.md

mcp-confluent-gateway

Author

confluentinc

Quick Info

Actions

Tags