@confluentinc/mcp-confluent 1.0.6 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (145) hide show
  1. package/README.md +608 -297
  2. package/dist/cli.d.ts +3 -0
  3. package/dist/cli.d.ts.map +1 -1
  4. package/dist/cli.js +10 -0
  5. package/dist/cli.js.map +1 -1
  6. package/dist/confluent/client-manager.d.ts +9 -0
  7. package/dist/confluent/client-manager.d.ts.map +1 -1
  8. package/dist/confluent/client-manager.js +35 -4
  9. package/dist/confluent/client-manager.js.map +1 -1
  10. package/dist/confluent/middleware.d.ts +3 -2
  11. package/dist/confluent/middleware.d.ts.map +1 -1
  12. package/dist/confluent/middleware.js +9 -1
  13. package/dist/confluent/middleware.js.map +1 -1
  14. package/dist/confluent/node-deps.d.ts +60 -0
  15. package/dist/confluent/node-deps.d.ts.map +1 -0
  16. package/dist/confluent/node-deps.js +12 -0
  17. package/dist/confluent/node-deps.js.map +1 -0
  18. package/dist/confluent/telemetry.d.ts +18 -0
  19. package/dist/confluent/telemetry.d.ts.map +1 -0
  20. package/dist/confluent/telemetry.js +104 -0
  21. package/dist/confluent/telemetry.js.map +1 -0
  22. package/dist/confluent/tools/handlers/billing/list-billing-costs-handler.d.ts +11 -0
  23. package/dist/confluent/tools/handlers/billing/list-billing-costs-handler.d.ts.map +1 -0
  24. package/dist/confluent/tools/handlers/billing/list-billing-costs-handler.js +174 -0
  25. package/dist/confluent/tools/handlers/billing/list-billing-costs-handler.js.map +1 -0
  26. package/dist/confluent/tools/handlers/clusters/list-clusters-handler.d.ts +7 -141
  27. package/dist/confluent/tools/handlers/clusters/list-clusters-handler.d.ts.map +1 -1
  28. package/dist/confluent/tools/handlers/environments/list-environments-handler.d.ts +8 -164
  29. package/dist/confluent/tools/handlers/environments/list-environments-handler.d.ts.map +1 -1
  30. package/dist/confluent/tools/handlers/flink/catalog/catalog-resolver.d.ts +77 -0
  31. package/dist/confluent/tools/handlers/flink/catalog/catalog-resolver.d.ts.map +1 -0
  32. package/dist/confluent/tools/handlers/flink/catalog/catalog-resolver.js +136 -0
  33. package/dist/confluent/tools/handlers/flink/catalog/catalog-resolver.js.map +1 -0
  34. package/dist/confluent/tools/handlers/flink/catalog/describe-table-handler.d.ts +11 -0
  35. package/dist/confluent/tools/handlers/flink/catalog/describe-table-handler.d.ts.map +1 -0
  36. package/dist/confluent/tools/handlers/flink/catalog/describe-table-handler.js +111 -0
  37. package/dist/confluent/tools/handlers/flink/catalog/describe-table-handler.js.map +1 -0
  38. package/dist/confluent/tools/handlers/flink/catalog/get-table-info-handler.d.ts +11 -0
  39. package/dist/confluent/tools/handlers/flink/catalog/get-table-info-handler.d.ts.map +1 -0
  40. package/dist/confluent/tools/handlers/flink/catalog/get-table-info-handler.js +110 -0
  41. package/dist/confluent/tools/handlers/flink/catalog/get-table-info-handler.js.map +1 -0
  42. package/dist/confluent/tools/handlers/flink/catalog/list-catalogs-handler.d.ts +11 -0
  43. package/dist/confluent/tools/handlers/flink/catalog/list-catalogs-handler.d.ts.map +1 -0
  44. package/dist/confluent/tools/handlers/flink/catalog/list-catalogs-handler.js +74 -0
  45. package/dist/confluent/tools/handlers/flink/catalog/list-catalogs-handler.js.map +1 -0
  46. package/dist/confluent/tools/handlers/flink/catalog/list-databases-handler.d.ts +11 -0
  47. package/dist/confluent/tools/handlers/flink/catalog/list-databases-handler.d.ts.map +1 -0
  48. package/dist/confluent/tools/handlers/flink/catalog/list-databases-handler.js +81 -0
  49. package/dist/confluent/tools/handlers/flink/catalog/list-databases-handler.js.map +1 -0
  50. package/dist/confluent/tools/handlers/flink/catalog/list-tables-handler.d.ts +11 -0
  51. package/dist/confluent/tools/handlers/flink/catalog/list-tables-handler.d.ts.map +1 -0
  52. package/dist/confluent/tools/handlers/flink/catalog/list-tables-handler.js +90 -0
  53. package/dist/confluent/tools/handlers/flink/catalog/list-tables-handler.js.map +1 -0
  54. package/dist/confluent/tools/handlers/flink/diagnostics/check-health-handler.d.ts +11 -0
  55. package/dist/confluent/tools/handlers/flink/diagnostics/check-health-handler.d.ts.map +1 -0
  56. package/dist/confluent/tools/handlers/flink/diagnostics/check-health-handler.js +131 -0
  57. package/dist/confluent/tools/handlers/flink/diagnostics/check-health-handler.js.map +1 -0
  58. package/dist/confluent/tools/handlers/flink/diagnostics/detect-issues-handler.d.ts +11 -0
  59. package/dist/confluent/tools/handlers/flink/diagnostics/detect-issues-handler.d.ts.map +1 -0
  60. package/dist/confluent/tools/handlers/flink/diagnostics/detect-issues-handler.js +248 -0
  61. package/dist/confluent/tools/handlers/flink/diagnostics/detect-issues-handler.js.map +1 -0
  62. package/dist/confluent/tools/handlers/flink/diagnostics/metrics-helper.d.ts +88 -0
  63. package/dist/confluent/tools/handlers/flink/diagnostics/metrics-helper.d.ts.map +1 -0
  64. package/dist/confluent/tools/handlers/flink/diagnostics/metrics-helper.js +443 -0
  65. package/dist/confluent/tools/handlers/flink/diagnostics/metrics-helper.js.map +1 -0
  66. package/dist/confluent/tools/handlers/flink/diagnostics/query-profiler-handler.d.ts +11 -0
  67. package/dist/confluent/tools/handlers/flink/diagnostics/query-profiler-handler.d.ts.map +1 -0
  68. package/dist/confluent/tools/handlers/flink/diagnostics/query-profiler-handler.js +398 -0
  69. package/dist/confluent/tools/handlers/flink/diagnostics/query-profiler-handler.js.map +1 -0
  70. package/dist/confluent/tools/handlers/flink/flink-sql-helper.d.ts +23 -0
  71. package/dist/confluent/tools/handlers/flink/flink-sql-helper.d.ts.map +1 -0
  72. package/dist/confluent/tools/handlers/flink/flink-sql-helper.js +133 -0
  73. package/dist/confluent/tools/handlers/flink/flink-sql-helper.js.map +1 -0
  74. package/dist/confluent/tools/handlers/flink/get-flink-exceptions-handler.d.ts +11 -0
  75. package/dist/confluent/tools/handlers/flink/get-flink-exceptions-handler.d.ts.map +1 -0
  76. package/dist/confluent/tools/handlers/flink/get-flink-exceptions-handler.js +72 -0
  77. package/dist/confluent/tools/handlers/flink/get-flink-exceptions-handler.js.map +1 -0
  78. package/dist/confluent/tools/handlers/flink/list-flink-statements-handler.d.ts.map +1 -1
  79. package/dist/confluent/tools/handlers/flink/list-flink-statements-handler.js +20 -3
  80. package/dist/confluent/tools/handlers/flink/list-flink-statements-handler.js.map +1 -1
  81. package/dist/confluent/tools/handlers/kafka/consume-kafka-messages-handler.d.ts +6 -54
  82. package/dist/confluent/tools/handlers/kafka/consume-kafka-messages-handler.d.ts.map +1 -1
  83. package/dist/confluent/tools/handlers/kafka/consume-kafka-messages-handler.js +1 -1
  84. package/dist/confluent/tools/handlers/kafka/consume-kafka-messages-handler.js.map +1 -1
  85. package/dist/confluent/tools/handlers/kafka/create-topics-handler.js +1 -1
  86. package/dist/confluent/tools/handlers/kafka/create-topics-handler.js.map +1 -1
  87. package/dist/confluent/tools/handlers/kafka/delete-topics-handler.js +1 -1
  88. package/dist/confluent/tools/handlers/kafka/delete-topics-handler.js.map +1 -1
  89. package/dist/confluent/tools/handlers/kafka/list-topics-handler.js +1 -1
  90. package/dist/confluent/tools/handlers/kafka/list-topics-handler.js.map +1 -1
  91. package/dist/confluent/tools/handlers/kafka/produce-kafka-message-handler.js +1 -1
  92. package/dist/confluent/tools/handlers/kafka/produce-kafka-message-handler.js.map +1 -1
  93. package/dist/confluent/tools/handlers/metrics/list-metrics-handler.d.ts +11 -0
  94. package/dist/confluent/tools/handlers/metrics/list-metrics-handler.d.ts.map +1 -0
  95. package/dist/confluent/tools/handlers/metrics/list-metrics-handler.js +193 -0
  96. package/dist/confluent/tools/handlers/metrics/list-metrics-handler.js.map +1 -0
  97. package/dist/confluent/tools/handlers/metrics/query-metrics-handler.d.ts +11 -0
  98. package/dist/confluent/tools/handlers/metrics/query-metrics-handler.d.ts.map +1 -0
  99. package/dist/confluent/tools/handlers/metrics/query-metrics-handler.js +224 -0
  100. package/dist/confluent/tools/handlers/metrics/query-metrics-handler.js.map +1 -0
  101. package/dist/confluent/tools/handlers/schema/delete-schema-handler.d.ts +10 -0
  102. package/dist/confluent/tools/handlers/schema/delete-schema-handler.d.ts.map +1 -0
  103. package/dist/confluent/tools/handlers/schema/delete-schema-handler.js +71 -0
  104. package/dist/confluent/tools/handlers/schema/delete-schema-handler.js.map +1 -0
  105. package/dist/confluent/tools/handlers/schema/list-schemas-handler.d.ts.map +1 -1
  106. package/dist/confluent/tools/handlers/schema/list-schemas-handler.js +1 -5
  107. package/dist/confluent/tools/handlers/schema/list-schemas-handler.js.map +1 -1
  108. package/dist/confluent/tools/tool-factory.d.ts.map +1 -1
  109. package/dist/confluent/tools/tool-factory.js +26 -0
  110. package/dist/confluent/tools/tool-factory.js.map +1 -1
  111. package/dist/confluent/tools/tool-name.d.ts +14 -1
  112. package/dist/confluent/tools/tool-name.d.ts.map +1 -1
  113. package/dist/confluent/tools/tool-name.js +13 -0
  114. package/dist/confluent/tools/tool-name.js.map +1 -1
  115. package/dist/env-schema.d.ts +17 -62
  116. package/dist/env-schema.d.ts.map +1 -1
  117. package/dist/env-schema.js +37 -2
  118. package/dist/env-schema.js.map +1 -1
  119. package/dist/env.d.ts +8 -1
  120. package/dist/env.d.ts.map +1 -1
  121. package/dist/index.js +67 -5
  122. package/dist/index.js.map +1 -1
  123. package/dist/logger.d.ts +2 -1
  124. package/dist/logger.d.ts.map +1 -1
  125. package/dist/logger.js +1 -1
  126. package/dist/logger.js.map +1 -1
  127. package/dist/mcp/transports/auth.d.ts +55 -0
  128. package/dist/mcp/transports/auth.d.ts.map +1 -0
  129. package/dist/mcp/transports/auth.js +127 -0
  130. package/dist/mcp/transports/auth.js.map +1 -0
  131. package/dist/mcp/transports/index.d.ts +1 -0
  132. package/dist/mcp/transports/index.d.ts.map +1 -1
  133. package/dist/mcp/transports/index.js +1 -0
  134. package/dist/mcp/transports/index.js.map +1 -1
  135. package/dist/mcp/transports/manager.d.ts +13 -1
  136. package/dist/mcp/transports/manager.d.ts.map +1 -1
  137. package/dist/mcp/transports/manager.js +20 -2
  138. package/dist/mcp/transports/manager.js.map +1 -1
  139. package/dist/mcp/transports/server.d.ts +10 -1
  140. package/dist/mcp/transports/server.d.ts.map +1 -1
  141. package/dist/mcp/transports/server.js +12 -2
  142. package/dist/mcp/transports/server.js.map +1 -1
  143. package/dist/print-md-schema.js +2 -2
  144. package/dist/print-md-schema.js.map +1 -1
  145. package/package.json +20 -9
package/README.md CHANGED
@@ -1,6 +1,9 @@
1
1
  # mcp-confluent
2
2
 
3
- An MCP server implementation that enables AI assistants to interact with Confluent Cloud REST APIs. This server allows AI tools like Claude Desktop and Goose CLI to manage Kafka topics, connectors, and Flink SQL statements through natural language interactions.
3
+ [![npm version](https://img.shields.io/npm/v/@confluentinc/mcp-confluent.svg)](https://www.npmjs.com/package/@confluentinc/mcp-confluent)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5
+
6
+ An [MCP server](https://modelcontextprotocol.io/) that enables AI assistants to interact with Confluent Cloud through natural language. It provides 37+ tools across Kafka, Flink SQL, Schema Registry, Connectors, Tableflow, and more -- usable from any MCP-compatible client including Claude Desktop, Claude Code, Cursor, VS Code, Goose, and Gemini CLI.
4
7
 
5
8
  <a href="https://glama.ai/mcp/servers/@confluentinc/mcp-confluent">
6
9
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@confluentinc/mcp-confluent/badge" alt="mcp-confluent MCP server" />
@@ -18,60 +21,102 @@ An MCP server implementation that enables AI assistants to interact with Conflue
18
21
 
19
22
  ![Claude Desktop Demo](assets/claude-desktop-demo.gif)
20
23
 
24
+ ## Quick Start
25
+
26
+ > **Prerequisites:** [Node.js 22+](https://nodejs.org/) and a [Confluent Cloud](https://confluent.cloud/) account.
27
+
28
+ ```bash
29
+ # Install and run
30
+ npx -y @confluentinc/mcp-confluent -e /path/to/.env
31
+ ```
32
+
33
+ Or install the [npm package](https://www.npmjs.com/package/@confluentinc/mcp-confluent) directly. See [Getting Started](#getting-started) for full setup instructions and [Configuring MCP Clients](#configuring-claude-desktop) for integration with your preferred AI tool.
34
+
21
35
  ## Table of Contents
22
36
 
23
- - [mcp-confluent](#mcp-confluent)
24
- - [Demo](#demo)
25
- - [Goose CLI](#goose-cli)
26
- - [Claude Desktop](#claude-desktop)
27
- - [Table of Contents](#table-of-contents)
28
- - [User Guide](#user-guide)
29
- - [Getting Started](#getting-started)
30
- - [Configuration](#configuration)
31
- - [Prerequisites \& Setup for Tableflow Commands](#prerequisites--setup-for-tableflow-commands)
32
- - [Environment Variables Reference](#environment-variables-reference)
33
- - [Usage](#usage)
34
- - [Configuring Claude Desktop](#configuring-claude-desktop)
35
- - [Configuring Goose CLI](#configuring-goose-cli)
36
- - [mcp-confluent CLI Usage](#mcp-confluent-cli-usage)
37
- - [Basic Usage](#basic-usage)
38
- - [Example: Deploy using all transports](#example-deploy-using-all-transports)
39
- - [Example: Allow Only Specific Tools](#example-allow-only-specific-tools)
40
- - [Example: Block Certain Tools](#example-block-certain-tools)
41
- - [Example: Use Tool Lists from Files](#example-use-tool-lists-from-files)
42
- - [Example: List All Available Tools](#example-list-all-available-tools)
43
- - [Developer Guide](#developer-guide)
44
- - [Project Structure](#project-structure)
45
- - [Building and Running](#building-and-running)
46
- - [Docker](#docker)
47
- - [Prerequisites](#prerequisites)
48
- - [Environment Variables](#environment-variables)
49
- - [Building and Running with Docker](#building-and-running-with-docker)
50
- - [Building and Running with Docker Compose](#building-and-running-with-docker-compose)
51
- - [Testing](#testing)
52
- - [MCP Inspector](#mcp-inspector)
53
- - [Adding a New Tool](#adding-a-new-tool)
54
- - [Generating Types](#generating-types)
55
- - [Contributing](#contributing)
37
+ - [Quick Start](#quick-start)
38
+ - [Available Tools](#available-tools)
39
+ - [Confluent Cloud](#available-tools-for-confluent-cloud)
40
+ - [Local Confluent](#available-tools-for-local-confluent)
41
+ - [User Guide](#user-guide)
42
+ - [Getting Started](#getting-started)
43
+ - [Configuration](#configuration)
44
+ - [Authentication for HTTP/SSE Transports](#authentication-for-httpsse-transports)
45
+ - [Environment Variables Reference](#environment-variables-reference)
46
+ - [Usage](#usage)
47
+ - [Configuring MCP Clients](#configuring-claude-desktop)
48
+ - [CLI Usage](#mcp-confluent-cli-usage)
49
+ - [Flink Example Workflows](#flink-example-workflows)
50
+ - [Developer Guide](#developer-guide)
51
+ - [Local Development with an MCP Client](#local-development-with-an-mcp-client)
52
+ - [Troubleshooting](#troubleshooting)
53
+
54
+ ## Available Tools
55
+
56
+ Only the tools whose required environment variables are configured will be enabled. You can also list all available tools via the CLI:
57
+
58
+ ```bash
59
+ npx -y @confluentinc/mcp-confluent --list-tools
60
+ ```
61
+
62
+ ### Available Tools for Confluent Cloud
63
+
64
+ These tools require endpoints and authentication against specific Confluent Cloud components. Refer to [`.env.example`](.env.example) for the full set of configuration variables.
65
+
66
+ | Category | Tools | Description |
67
+ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
68
+ | **Kafka** | `list-topics`, `create-topics`, `delete-topics`, `produce-message`, `consume-messages`, `alter-topic-config`, `get-topic-config` | Manage topics, produce/consume messages, configure topic settings |
69
+ | **Flink SQL** | `create-flink-statement`, `list-flink-statements`, `read-flink-statement`, `delete-flink-statements`, `get-flink-statement-exceptions` | Create and manage Flink SQL statements |
70
+ | **Flink Catalog** | `list-flink-catalogs`, `list-flink-databases`, `list-flink-tables`, `describe-flink-table`, `get-flink-table-info` | Explore Flink catalogs, databases, and table schemas |
71
+ | **Flink Diagnostics** | `check-flink-statement-health`, `detect-flink-statement-issues`, `get-flink-statement-profile` | Health checks, issue detection, and query profiling |
72
+ | **Connectors** | `list-connectors`, `read-connector`, `create-connector`, `delete-connector` | Manage Kafka Connect connectors |
73
+ | **Schema Registry** | `list-schemas`, `delete-schema` | List, inspect, and delete data schemas |
74
+ | **Catalog & Tags** | `search-topics-by-tag`, `search-topics-by-name`, `create-topic-tags`, `delete-tag`, `remove-tag-from-entity`, `add-tags-to-topic`, `list-tags` | Organize and search topics using tags |
75
+ | **Environments & Clusters** | `list-environments`, `read-environment`, `list-clusters` | Discover Confluent Cloud resources |
76
+ | **Tableflow** | `create-tableflow-topic`, `list-tableflow-topics`, `read-tableflow-topic`, `update-tableflow-topic`, `delete-tableflow-topic`, `list-tableflow-regions` | Manage Tableflow-enabled topics |
77
+ | **Tableflow Catalog** | `create-tableflow-catalog-integration`, `list-tableflow-catalog-integrations`, `read-tableflow-catalog-integration`, `update-tableflow-catalog-integration`, `delete-tableflow-catalog-integration` | Manage Tableflow catalog integrations (e.g., AWS Glue) |
78
+ | **Metrics** | `list-available-metrics`, `query-metrics` | Discover and query Confluent Cloud operational metrics |
79
+ | **Billing** | `list-billing-costs` | Query billing and cost data |
80
+
81
+ ### Available Tools for Local Confluent
82
+
83
+ These tools only require Kafka or Schema Registry endpoints - no Confluent Cloud API key/secret is needed. Ideal for local development with Docker Compose or self-managed clusters.
84
+
85
+ ```properties
86
+ # minimal .env for local development
87
+ BOOTSTRAP_SERVERS="localhost:9092"
88
+ SCHEMA_REGISTRY_ENDPOINT="http://localhost:8081"
89
+ ```
90
+
91
+ | Category | Tools | Description |
92
+ | ------------------- | -------------------------------------------------------------------------------------- | --------------------------------------- |
93
+ | **Kafka** | `list-topics`, `create-topics`, `delete-topics`, `produce-message`, `consume-messages` | Manage topics, produce/consume messages |
94
+ | **Schema Registry** | `list-schemas`, `delete-schema` | List, inspect, and delete data schemas |
56
95
 
57
96
  ## User Guide
58
97
 
59
98
  ### Getting Started
60
99
 
61
- 1. **Create a `.env` file:** Copy the example `.env` file structure (shown below) into a new file named `.env` in the root of your project.
62
- 2. **Populate the `.env` file:** Fill in the necessary values for your Confluent Cloud environment. See the [Configuration](#configuration) section for details on each variable.
63
- 3. **Install Node.js** (if not already installed)
64
- - We recommend using [NVM](https://github.com/nvm-sh/nvm) (Node Version Manager) to manage Node.js versions
65
- - Install and use Node.js:
100
+ #### Prerequisites
101
+
102
+ - **Node.js 22 or later** -- we recommend using [NVM](https://github.com/nvm-sh/nvm) to manage versions:
103
+ ```bash
104
+ nvm install 22
105
+ nvm use 22
106
+ ```
107
+ - A **Confluent Cloud** account with appropriate API keys
66
108
 
67
- ```bash
68
- nvm install 22
69
- nvm use 22
70
- ```
109
+ #### Setup
110
+
111
+ 1. **Create a `.env` file:** Copy the provided `.env.example` file to `.env` in the root of your project:
112
+ ```bash
113
+ cp .env.example .env
114
+ ```
115
+ 2. **Populate the `.env` file:** Fill in the necessary values for your Confluent Cloud environment. See the [Configuration](#configuration) section for details on each variable.
71
116
 
72
117
  ### Configuration
73
118
 
74
- Create a `.env` file in the root directory of your project with the following configuration:
119
+ Copy `.env.example` to `.env` in the root directory and fill in your values. See the example structure below:
75
120
 
76
121
  <details>
77
122
  <summary>Example .env file structure</summary>
@@ -112,47 +157,124 @@ It is crucial to set up the necessary roles and policies in your cloud environme
112
157
 
113
158
  Please refer to the following Confluent Cloud documentation for detailed instructions on setting up these permissions and integrating with custom storage and Glue:
114
159
 
115
- * **Confluent Cloud Tableflow Quick Start with Custom Storage & Glue:**
116
- [https://docs.confluent.io/cloud/current/topics/tableflow/get-started/quick-start-custom-storage-glue.html](https://docs.confluent.io/cloud/current/topics/tableflow/get-started/quick-start-custom-storage-glue.html)
160
+ - **Confluent Cloud Tableflow Quick Start with Custom Storage & Glue:**
161
+ [https://docs.confluent.io/cloud/current/topics/tableflow/get-started/quick-start-custom-storage-glue.html](https://docs.confluent.io/cloud/current/topics/tableflow/get-started/quick-start-custom-storage-glue.html)
117
162
 
118
163
  Ensuring these prerequisites are met will prevent authorization errors when the `mcp-server` attempts to provision or manage Tableflow-enabled tables.
119
164
 
165
+ ### Authentication for HTTP/SSE Transports
166
+
167
+ When using HTTP or SSE transports, the MCP server requires API key authentication to prevent unauthorized access and protect against DNS rebinding attacks. This is **enabled by default**.
168
+
169
+ #### Generating an API Key
170
+
171
+ Generate a secure API key using the built-in utility:
172
+
173
+ ```bash
174
+ npx @confluentinc/mcp-confluent --generate-key
175
+ ```
176
+
177
+ This will output a 64-character key generated using secure cryptography:
178
+
179
+ ```
180
+ Generated MCP API Key:
181
+ ================================================================
182
+ a1b2c3d4e5f6...your-64-char-key-here...
183
+ ================================================================
184
+
185
+ ```
186
+
187
+ #### Configuring Authentication
188
+
189
+ Add the generated key to your `.env` file:
190
+
191
+ ```properties
192
+ # MCP Server Authentication (required for HTTP/SSE transports)
193
+ MCP_API_KEY=your-generated-64-char-key-here
194
+ ```
195
+
196
+ #### Making Authenticated Requests
197
+
198
+ Include the API key in the `cflt-mcp-api-Key` header for all HTTP/SSE requests:
199
+
200
+ ```bash
201
+ curl -H "cflt-mcp-api-Key: your-api-key" http://localhost:8080/mcp
202
+ ```
203
+
204
+ #### DNS Rebinding Protection
205
+
206
+ The server includes additional protections against DNS rebinding attacks:
207
+
208
+ - **Host Header Validation**: Only requests with allowed Host headers are accepted
209
+
210
+ Configure allowed hosts if needed:
211
+
212
+ ```properties
213
+ # Allow additional hosts (comma-separated)
214
+ MCP_ALLOWED_HOSTS=localhost,127.0.0.1,myhost.local
215
+ ```
216
+
217
+ #### Additional security to prevent internet exposure of MCP server
218
+
219
+ - **Localhost Binding**: Server binds to `127.0.0.1` by default (not `0.0.0.0`)
220
+
221
+ #### Disabling Authentication (Development Only)
222
+
223
+ For local development, you can disable authentication:
224
+
225
+ ```bash
226
+ # Via CLI flag
227
+ npx @confluentinc/mcp-confluent -e .env --transport http --disable-auth
228
+
229
+ # Or via environment variable
230
+ MCP_AUTH_DISABLED=true
231
+ ```
232
+
233
+ > [!WARNING]
234
+ > Never disable authentication in production or when the server is network-accessible.
235
+
120
236
  ### Environment Variables Reference
121
237
 
122
- | Variable | Description | Default Value | Required |
123
- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------- |
124
- | HTTP_HOST | Host to bind for HTTP transport. 0.0.0.0 means all interfaces. (string) | "0.0.0.0" | Yes |
125
- | HTTP_MCP_ENDPOINT_PATH | HTTP endpoint path for MCP transport (e.g., '/mcp') (string) | "/mcp" | Yes |
126
- | HTTP_PORT | Port to use for HTTP transport (number (min: 0)) | 8080 | Yes |
127
- | LOG_LEVEL | Log level for application logging (trace, debug, info, warn, error, fatal) (effects) | "info" | Yes |
128
- | SSE_MCP_ENDPOINT_PATH | SSE endpoint path for establishing SSE connections (e.g., '/sse', '/events') (string) | "/sse" | Yes |
129
- | SSE_MCP_MESSAGE_ENDPOINT_PATH | SSE message endpoint path for receiving messages (e.g., '/messages', '/events/messages') (string) | "/messages" | Yes |
130
- | BOOTSTRAP_SERVERS | List of Kafka broker addresses in the format host1:port1,host2:port2 used to establish initial connection to the Kafka cluster (string) | | No |
131
- | CONFLUENT_CLOUD_API_KEY | Master API key for Confluent Cloud platform administration, enabling management of resources across your organization (string (min: 1)) | | No |
132
- | CONFLUENT_CLOUD_API_SECRET | Master API secret paired with CONFLUENT_CLOUD_API_KEY for comprehensive Confluent Cloud platform administration (string (min: 1)) | | No |
133
- | CONFLUENT_CLOUD_REST_ENDPOINT | Base URL for Confluent Cloud's REST API services (default) | | No |
134
- | FLINK_API_KEY | Authentication key for accessing Confluent Cloud's Flink services, including compute pools and SQL statement management (string (min: 1)) | | No |
135
- | FLINK_API_SECRET | Secret token paired with FLINK_API_KEY for authenticated access to Confluent Cloud's Flink services (string (min: 1)) | | No |
136
- | FLINK_COMPUTE_POOL_ID | Unique identifier for the Flink compute pool, must start with 'lfcp-' prefix (string) | | No |
137
- | FLINK_DATABASE_NAME | Name of the associated Kafka cluster used as a database reference in Flink SQL operations (string (min: 1)) | | No |
138
- | FLINK_ENV_ID | Unique identifier for the Flink environment, must start with 'env-' prefix (string) | | No |
139
- | FLINK_ENV_NAME | Human-readable name for the Flink environment used for identification and display purposes (string (min: 1)) | | No |
140
- | FLINK_ORG_ID | Organization identifier within Confluent Cloud for Flink resource management (string (min: 1)) | | No |
141
- | FLINK_REST_ENDPOINT | Base URL for Confluent Cloud's Flink REST API endpoints used for SQL statement and compute pool management (string) | | No |
142
- | KAFKA_API_KEY | Authentication credential (username) required to establish secure connection with the Kafka cluster (string (min: 1)) | | No |
143
- | KAFKA_API_SECRET | Authentication credential (password) paired with KAFKA_API_KEY for secure Kafka cluster access (string (min: 1)) | | No |
144
- | KAFKA_CLUSTER_ID | Unique identifier for the Kafka cluster within Confluent Cloud ecosystem (string (min: 1)) | | No |
145
- | KAFKA_ENV_ID | Environment identifier for Kafka cluster, must start with 'env-' prefix (string) | | No |
146
- | KAFKA_REST_ENDPOINT | REST API endpoint for Kafka cluster management and administration (string) | | No |
147
- | SCHEMA_REGISTRY_API_KEY | Authentication key for accessing Schema Registry services to manage and validate data schemas (string (min: 1)) | | No |
148
- | SCHEMA_REGISTRY_API_SECRET | Authentication secret paired with SCHEMA_REGISTRY_API_KEY for secure Schema Registry access (string (min: 1)) | | No |
149
- | SCHEMA_REGISTRY_ENDPOINT | URL endpoint for accessing Schema Registry services to manage data schemas (string) | | No |
150
- | TABLEFLOW_API_KEY | Authentication key for accessing Confluent Cloud's Tableflow services (string (min: 1)) | | No |
151
- | TABLEFLOW_API_SECRET | Authentication secret paired with TABLEFLOW_API_KEY for secure Tableflow access (string (min: 1)) | | No |
238
+ | Variable | Description | Default Value | Required |
239
+ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------- |
240
+ | HTTP_HOST | Host to bind for HTTP transport. Defaults to localhost only for security. | "127.0.0.1" | Yes |
241
+ | HTTP_MCP_ENDPOINT_PATH | HTTP endpoint path for MCP transport (e.g., '/mcp') (string) | "/mcp" | Yes |
242
+ | HTTP_PORT | Port to use for HTTP transport (number (min: 0)) | 8080 | Yes |
243
+ | LOG_LEVEL | Log level for application logging (trace, debug, info, warn, error, fatal) | "info" | Yes |
244
+ | MCP_API_KEY | API key for HTTP/SSE authentication. Generate using `--generate-key`. Required when auth is enabled. | | No\* |
245
+ | MCP_AUTH_DISABLED | Disable authentication for HTTP/SSE transports. WARNING: Only use in development environments. | false | No |
246
+ | MCP_ALLOWED_HOSTS | Comma-separated list of allowed Host header values for DNS rebinding protection. | "localhost,127.0.0.1" | No |
247
+ | SSE_MCP_ENDPOINT_PATH | SSE endpoint path for establishing SSE connections (e.g., '/sse', '/events') (string) | "/sse" | Yes |
248
+ | SSE_MCP_MESSAGE_ENDPOINT_PATH | SSE message endpoint path for receiving messages (e.g., '/messages', '/events/messages') (string) | "/messages" | Yes |
249
+ | BOOTSTRAP_SERVERS | List of Kafka broker addresses in the format host1:port1,host2:port2 used to establish initial connection to the Kafka cluster (string) | | No |
250
+ | CONFLUENT_CLOUD_API_KEY | Master API key for Confluent Cloud platform administration, enabling management of resources across your organization (string (min: 1)) | | No |
251
+ | CONFLUENT_CLOUD_API_SECRET | Master API secret paired with CONFLUENT_CLOUD_API_KEY for comprehensive Confluent Cloud platform administration (string (min: 1)) | | No |
252
+ | CONFLUENT_CLOUD_REST_ENDPOINT | Base URL for Confluent Cloud's REST API services (default) | | No |
253
+ | FLINK_API_KEY | Authentication key for accessing Confluent Cloud's Flink services, including compute pools and SQL statement management (string (min: 1)) | | No |
254
+ | FLINK_API_SECRET | Secret token paired with FLINK_API_KEY for authenticated access to Confluent Cloud's Flink services (string (min: 1)) | | No |
255
+ | FLINK_COMPUTE_POOL_ID | Unique identifier for the Flink compute pool, must start with 'lfcp-' prefix (string) | | No |
256
+ | FLINK_DATABASE_NAME | Name of the associated Kafka cluster used as a database reference in Flink SQL operations (string (min: 1)) | | No |
257
+ | FLINK_ENV_ID | Unique identifier for the Flink environment, must start with 'env-' prefix (string) | | No |
258
+ | FLINK_ENV_NAME | Human-readable name for the Flink environment used for identification and display purposes (string (min: 1)) | | No |
259
+ | FLINK_ORG_ID | Organization identifier within Confluent Cloud for Flink resource management (string (min: 1)) | | No |
260
+ | FLINK_REST_ENDPOINT | Base URL for Confluent Cloud's Flink REST API endpoints used for SQL statement and compute pool management (string) | | No |
261
+ | KAFKA_API_KEY | Authentication credential (username) required to establish secure connection with the Kafka cluster (string (min: 1)) | | No |
262
+ | KAFKA_API_SECRET | Authentication credential (password) paired with KAFKA_API_KEY for secure Kafka cluster access (string (min: 1)) | | No |
263
+ | KAFKA_CLUSTER_ID | Unique identifier for the Kafka cluster within Confluent Cloud ecosystem (string (min: 1)) | | No |
264
+ | KAFKA_ENV_ID | Environment identifier for Kafka cluster, must start with 'env-' prefix (string) | | No |
265
+ | KAFKA_REST_ENDPOINT | REST API endpoint for Kafka cluster management and administration (string) | | No |
266
+ | SCHEMA_REGISTRY_API_KEY | Authentication key for accessing Schema Registry services to manage and validate data schemas (string (min: 1)) | | No |
267
+ | SCHEMA_REGISTRY_API_SECRET | Authentication secret paired with SCHEMA_REGISTRY_API_KEY for secure Schema Registry access (string (min: 1)) | | No |
268
+ | SCHEMA_REGISTRY_ENDPOINT | URL endpoint for accessing Schema Registry services to manage data schemas (string) | | No |
269
+ | TABLEFLOW_API_KEY | Authentication key for accessing Confluent Cloud's Tableflow services (string (min: 1)) | | No |
270
+ | TABLEFLOW_API_SECRET | Authentication secret paired with TABLEFLOW_API_KEY for secure Tableflow access (string (min: 1)) | | No |
271
+ | TELEMETRY_ENDPOINT | Base URL for Confluent Cloud Telemetry API (metrics) | "https://api.telemetry.confluent.cloud" | No |
272
+ | TELEMETRY_API_KEY | Optional API key for telemetry access. Falls back to CONFLUENT_CLOUD_API_KEY if not set. (See [Metrics API authentication docs](https://docs.confluent.io/cloud/current/monitoring/metrics-api.html#create-an-api-key-to-authenticate-to-the-metrics-api).) | | No |
273
+ | TELEMETRY_API_SECRET | Optional API secret for telemetry access. Falls back to CONFLUENT_CLOUD_API_SECRET if not set. (See [Metrics API authentication docs](https://docs.confluent.io/cloud/current/monitoring/metrics-api.html#create-an-api-key-to-authenticate-to-the-metrics-api).) | | No |
152
274
 
153
275
  ### Usage
154
276
 
155
- This MCP server is designed to be used with various MCP clients, such as Claude Desktop or Goose CLI/Desktop. The specific configuration and interaction will depend on the client you are using. However, the general steps are:
277
+ This MCP server is designed to be used with various MCP clients, such as Claude Desktop or Goose CLI/Desktop. The specific configuration and interaction will depend on the client you are using. However, the general steps are:
156
278
 
157
279
  1. **Start the Server:** You can run the MCP server in one of two ways:
158
280
  - **From source:** Follow the instructions in the [Developer Guide](#developer-guide) to build and run the server from source. This typically involves:
@@ -164,11 +286,11 @@ This MCP server is designed to be used with various MCP clients, such as Claude
164
286
  npx -y @confluentinc/mcp-confluent -e /path/to/confluent-mcp-server/.env
165
287
  ```
166
288
 
167
- 2. **Configure your MCP Client:** Each client will have its own way of specifying the MCP server's address and any required credentials. You'll need to configure your client (e.g., Claude, Goose) to connect to the address where this server is running (likely `localhost` with a specific port). The port the server runs on may be configured by an environment variable.
289
+ 2. **Configure your MCP Client:** Each client will have its own way of specifying the MCP server's address and any required credentials. You'll need to configure your client (e.g., Claude, Goose) to connect to the address where this server is running (likely `localhost` with a specific port). The port the server runs on may be configured by an environment variable.
168
290
 
169
- 3. **Start the MCP Client:** Once your client is configured to connect to the MCP server, you can start your mcp client and on startup - it will stand up an instance of this MCP server locally. This instance will be responsible for managing data schemas and interacting with Confluent Cloud on your behalf.
291
+ 3. **Start the MCP Client:** Once your client is configured to connect to the MCP server, you can start your mcp client and on startup - it will stand up an instance of this MCP server locally. This instance will be responsible for managing data schemas and interacting with Confluent Cloud on your behalf.
170
292
 
171
- 4. **Interact with Confluent through the Client:** Once the client is connected, you can use the client's interface to interact with Confluent Cloud resources. The client will send requests to this MCP server, which will then interact with Confluent Cloud on your behalf.
293
+ 4. **Interact with Confluent through the Client:** Once the client is connected, you can use the client's interface to interact with Confluent Cloud resources. The client will send requests to this MCP server, which will then interact with Confluent Cloud on your behalf.
172
294
 
173
295
  ### Configuring Claude Desktop
174
296
 
@@ -177,7 +299,7 @@ See [here](https://modelcontextprotocol.io/quickstart/user) for more details abo
177
299
  To configure Claude Desktop to use this MCP server:
178
300
 
179
301
  1. **Open Claude Desktop Configuration**
180
- - On Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
302
+ - On Mac: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
181
303
  - On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
182
304
 
183
305
  2. **Edit Configuration File**
@@ -194,8 +316,8 @@ To configure Claude Desktop to use this MCP server:
194
316
  "command": "node",
195
317
  "args": [
196
318
  "/path/to/confluent-mcp-server/dist/index.js",
197
- "--env-file",
198
- "/path/to/confluent-mcp-server/.env",
319
+ "--env-file",
320
+ "/path/to/confluent-mcp-server/.env"
199
321
  ]
200
322
  }
201
323
  }
@@ -213,7 +335,7 @@ To configure Claude Desktop to use this MCP server:
213
335
  "confluent": {
214
336
  "command": "npx",
215
337
  "args": [
216
- "-y"
338
+ "-y",
217
339
  "@confluentinc/mcp-confluent",
218
340
  "-e",
219
341
  "/path/to/confluent-mcp-server/.env"
@@ -227,7 +349,7 @@ To configure Claude Desktop to use this MCP server:
227
349
 
228
350
  Replace `/path/to/confluent-mcp-server/` with the actual path where you've installed this MCP server.
229
351
 
230
- 1. **Restart Claude Desktop**
352
+ 3. **Restart Claude Desktop**
231
353
  - Close and reopen Claude Desktop for the changes to take effect
232
354
  - The MCP server will automatically start when Claude Desktop launches
233
355
 
@@ -275,6 +397,146 @@ Replace `/path/to/confluent-mcp-server/` with the actual path where you've insta
275
397
 
276
398
  ![Goose Configure](assets/goose-configure.png)
277
399
 
400
+ ### Configuring Gemini CLI
401
+
402
+ For detailed information about Gemini CLI extensions and MCP servers, please refer to the official documentation:
403
+
404
+ - [Gemini CLI Extensions](https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md)
405
+ - [Gemini CLI MCP Server Tools](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)
406
+
407
+ Here's how to get `mcp-confluent` running with Gemini CLI:
408
+
409
+ 1. **Install Gemini CLI:**
410
+ If you haven't already, install the Gemini CLI. You can find installation instructions on the [official GitHub repository](https://github.com/google-gemini/gemini-cli).
411
+
412
+ 2. **Install the `mcp-confluent` Extension:**
413
+
414
+ ```bash
415
+ gemini extensions install https://github.com/confluentinc/mcp-confluent
416
+ # Navigate to the root directory of this project (where `gemini-extension.json` is located) and run:
417
+ # gemini extensions install .
418
+ ```
419
+
420
+ This command registers the `mcp-confluent` server with Gemini CLI and creates a dedicated directory for it under `~/.gemini/extensions/mcp-confluent`.
421
+
422
+ 3. **Provide Environment Variables:**
423
+ The extension requires your Confluent Cloud credentials and configuration to be available in a `.env` file.
424
+ - First, ensure you have a correctly populated `.env` file in the root of this project. For instructions, see the [Configuration](#configuration) section.
425
+ - Next, copy your `.env` file into the extension's directory so Gemini CLI can access it (the Gemini extension expects the `.env` file at `${extensionPath}${pathSeparator}.env`; see [the variables documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/reference.md#variables) for details):
426
+
427
+ ```bash
428
+ cp .env ~/.gemini/extensions/mcp-confluent/.env
429
+ ```
430
+
431
+ 4. **Verify and Use:**
432
+ You can now start using the Confluent tools via Gemini CLI. To verify that the tools are available, you can list them:
433
+
434
+ ```bash
435
+ gemini -l
436
+ # or `gemini extensions list`
437
+ ```
438
+
439
+ And here's an example of invoking a tool:
440
+
441
+ ```bash
442
+
443
+ gemini
444
+ ....
445
+
446
+ 🟢 mcp-confluent (from mcp-confluent) - Ready (24 tools)
447
+ ....
448
+
449
+ Using: 1 MCP server (ctrl+t to toggle)
450
+ ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
451
+ │ > list topics │
452
+ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
453
+
454
+ ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
455
+ │ ✓ list-topics (mcp-confluent MCP Server) {} │
456
+ │ │
457
+ │ Kafka topics: │
458
+ │ products_summarized,products,topic_8,products_summarized_with_embeddings,elastic_minimized,user_message_related_products,user_message_embeddin │
459
+ │ gs,dlq-lcc-d3738o,user_message,elastic │
460
+ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
461
+ ✦ Okay, I see the following topics: products_summarized, products, topic_8, products_summarized_with_embeddings, elastic_minimized,
462
+ user_message_related_products, user_message_embeddings, dlq-lcc-d3738o, user_message, and elastic.
463
+
464
+ ```
465
+
466
+ ### Configuring Claude Code
467
+
468
+ [Claude Code](https://docs.anthropic.com/en/docs/claude-code) supports MCP servers natively. Add the server to your project configuration:
469
+
470
+ ```bash
471
+ claude mcp add confluent -- npx -y @confluentinc/mcp-confluent -e /path/to/.env
472
+ ```
473
+
474
+ Or add it to your `.mcp.json` file directly:
475
+
476
+ ```json
477
+ {
478
+ "mcpServers": {
479
+ "confluent": {
480
+ "command": "npx",
481
+ "args": ["-y", "@confluentinc/mcp-confluent", "-e", "/path/to/.env"]
482
+ }
483
+ }
484
+ }
485
+ ```
486
+
487
+ ### Configuring Cursor
488
+
489
+ Add the MCP server to your Cursor configuration at `~/.cursor/mcp.json`:
490
+
491
+ ```json
492
+ {
493
+ "mcpServers": {
494
+ "confluent": {
495
+ "command": "npx",
496
+ "args": ["-y", "@confluentinc/mcp-confluent", "-e", "/path/to/.env"]
497
+ }
498
+ }
499
+ }
500
+ ```
501
+
502
+ See the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol) for more details.
503
+
504
+ ### Configuring VS Code
505
+
506
+ Add the MCP server to your VS Code user settings (`settings.json`) or workspace `.vscode/mcp.json`:
507
+
508
+ ```json
509
+ {
510
+ "mcp": {
511
+ "servers": {
512
+ "confluent": {
513
+ "command": "npx",
514
+ "args": ["-y", "@confluentinc/mcp-confluent", "-e", "/path/to/.env"]
515
+ }
516
+ }
517
+ }
518
+ }
519
+ ```
520
+
521
+ See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
522
+
523
+ ### Configuring Windsurf
524
+
525
+ Add the MCP server to your Windsurf configuration at `~/.codeium/windsurf/mcp_config.json`:
526
+
527
+ ```json
528
+ {
529
+ "mcpServers": {
530
+ "confluent": {
531
+ "command": "npx",
532
+ "args": ["-y", "@confluentinc/mcp-confluent", "-e", "/path/to/.env"]
533
+ }
534
+ }
535
+ }
536
+ ```
537
+
538
+ See the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/mcp) for more details.
539
+
278
540
  ### mcp-confluent CLI Usage
279
541
 
280
542
  The MCP server provides a flexible command line interface (CLI) for advanced configuration and control. The CLI allows you to specify environment files, transports, and fine-tune which tools are enabled or blocked.
@@ -284,7 +546,7 @@ The MCP server provides a flexible command line interface (CLI) for advanced con
284
546
  You can view all CLI options and help with:
285
547
 
286
548
  ```bash
287
- npx @confluentinc/mcp-confluent --help
549
+ npx @confluentinc/mcp-confluent --help
288
550
  ```
289
551
 
290
552
  <details>
@@ -306,6 +568,9 @@ Options:
306
568
  --block-tools-file <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.
307
569
  --list-tools Print the final set of enabled tool names (with descriptions) after allow/block filtering and exit. Does not start the server.
308
570
  --disable-confluent-cloud-tools Disable all tools that require Confluent Cloud REST APIs (cloud-only tools).
571
+ --disable-auth Disable authentication for HTTP/SSE transports. WARNING: Only use in development environments.
572
+ --allowed-hosts <hosts> Comma-separated list of allowed Host header values for DNS rebinding protection.
573
+ --generate-key Generate a secure API key for MCP_API_KEY and print it to stdout, then exit.
309
574
  -h, --help display help for command
310
575
  ```
311
576
 
@@ -339,53 +604,7 @@ npx @confluentinc/mcp-confluent -e .env --transport http,sse,stdio
339
604
  npx @confluentinc/mcp-confluent -e .env --allow-tools produce-message,consume-messages
340
605
  ```
341
606
 
342
- <details>
343
- <summary>Show output</summary>
344
-
345
- ```json
346
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-topics disabled due to allow/block list rules"}
347
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-topics disabled due to allow/block list rules"}
348
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-topics disabled due to allow/block list rules"}
349
- {"level":"info","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool produce-message enabled"}
350
- {"level":"info","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool consume-messages enabled"}
351
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-flink-statements disabled due to allow/block list rules"}
352
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-flink-statement disabled due to allow/block list rules"}
353
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-flink-statement disabled due to allow/block list rules"}
354
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-flink-statements disabled due to allow/block list rules"}
355
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-connectors disabled due to allow/block list rules"}
356
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-connector disabled due to allow/block list rules"}
357
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-connector disabled due to allow/block list rules"}
358
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-connector disabled due to allow/block list rules"}
359
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool search-topics-by-tag disabled due to allow/block list rules"}
360
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool search-topics-by-name disabled due to allow/block list rules"}
361
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-topic-tags disabled due to allow/block list rules"}
362
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-tag disabled due to allow/block list rules"}
363
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool remove-tag-from-entity disabled due to allow/block list rules"}
364
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool add-tags-to-topic disabled due to allow/block list rules"}
365
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-tags disabled due to allow/block list rules"}
366
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool alter-topic-config disabled due to allow/block list rules"}
367
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-clusters disabled due to allow/block list rules"}
368
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-environments disabled due to allow/block list rules"}
369
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-environment disabled due to allow/block list rules"}
370
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-schemas disabled due to allow/block list rules"}
371
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool get-topic-config disabled due to allow/block list rules"}
372
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool create-tableflow-topic disabled due to allow/block list rules"}
373
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool list-tableflow-regions disabled due to allow/block list rules"}
374
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool list-tableflow-topics disabled due to allow/block list rules"}
375
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool read-tableflow-topic disabled due to allow/block list rules"}
376
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool update-tableflow-topic disabled due to allow/block list rules"}
377
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool delete-tableflow-topic disabled due to allow/block list rules"}
378
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool create-tableflow-catalog-integration disabled due to allow/block list rules"}
379
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool list-tableflow-catalog-integrations disabled due to allow/block list rules"}
380
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool read-tableflow-catalog-integration disabled due to allow/block list rules"}
381
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool update-tableflow-catalog-integration disabled due to allow/block list rules"}
382
- {"level":"warn","time":"2025-05-14T16:52:34.923Z","pid":53394,"hostname":"YXR2D4NCM9","name":"mcp-confluent","msg":"Tool delete-tableflow-catalog-integration disabled due to allow/block list rules"}
383
- {"level":"info","time":"2025-05-14T16:52:34.924Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Starting transports: stdio on localhost:3000"}
384
- {"level":"info","time":"2025-05-14T16:52:34.924Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"STDIO transport connected"}
385
- {"level":"info","time":"2025-05-14T16:52:34.924Z","pid":46818,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"All transports started successfully"}
386
- ```
387
-
388
- </details>
607
+ Only the specified tools will be enabled; all others will be disabled.
389
608
 
390
609
  #### Example: Block Certain Tools
391
610
 
@@ -393,108 +612,16 @@ npx @confluentinc/mcp-confluent -e .env --allow-tools produce-message,consume-me
393
612
  npx @confluentinc/mcp-confluent -e .env --block-tools produce-message,consume-messages
394
613
  ```
395
614
 
396
- <details>
397
- <summary>Show output</summary>
398
-
399
- ```json
400
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-topics enabled"}
401
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-topics enabled"}
402
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-topics enabled"}
403
- {"level":"warn","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool produce-message disabled due to allow/block list rules"}
404
- {"level":"warn","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool consume-messages disabled due to allow/block list rules"}
405
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-flink-statements enabled"}
406
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-flink-statement enabled"}
407
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-flink-statement enabled"}
408
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-flink-statements enabled"}
409
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-connectors enabled"}
410
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-connector enabled"}
411
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-connector enabled"}
412
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-connector enabled"}
413
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool search-topics-by-tag enabled"}
414
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool search-topics-by-name enabled"}
415
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-topic-tags enabled"}
416
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-tag enabled"}
417
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool remove-tag-from-entity enabled"}
418
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool add-tags-to-topic enabled"}
419
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-tags enabled"}
420
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool alter-topic-config enabled"}
421
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-clusters enabled"}
422
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-environments enabled"}
423
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-environment enabled"}
424
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-schemas enabled"}
425
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool get-topic-config enabled"}
426
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-tableflow-topic enabled"}
427
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-tableflow-regions enabled"}
428
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-tableflow-topics enabled"}
429
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-tableflow-topic enabled"}
430
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool update-tableflow-topic enabled"}
431
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-tableflow-topic enabled"}
432
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-tableflow-catalog-integration enabled"}
433
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-tableflow-catalog-integrations enabled"}
434
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-tableflow-catalog-integration enabled"}
435
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool update-tableflow-catalog-integration enabled"}
436
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-tableflow-catalog-integration enabled"}
437
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Starting transports: stdio"}
438
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"STDIO transport connected"}
439
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"All transports started successfully"}
440
- ```
441
-
442
- </details>
615
+ All tools except the specified ones will be enabled.
443
616
 
444
617
  #### Example: Use Tool Lists from Files
445
618
 
619
+ You can also maintain allow/block lists in files (one tool name per line):
620
+
446
621
  ```bash
447
622
  npx -y @confluentinc/mcp-confluent -e .env --allow-tools-file allow.txt --block-tools-file block.txt
448
623
  ```
449
624
 
450
- <details>
451
- <summary>Show output</summary>
452
-
453
- ```json
454
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-topics enabled"}
455
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-topics enabled"}
456
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-topics enabled"}
457
- {"level":"warn","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool produce-message disabled due to allow/block list rules"}
458
- {"level":"warn","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool consume-messages disabled due to allow/block list rules"}
459
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-flink-statements enabled"}
460
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-flink-statement enabled"}
461
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-flink-statement enabled"}
462
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-flink-statements enabled"}
463
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-connectors enabled"}
464
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-connector enabled"}
465
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-connector enabled"}
466
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-connector enabled"}
467
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool search-topics-by-tag enabled"}
468
- {"level":"info","time":"2025-05-14T16:55:45.910Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool search-topics-by-name enabled"}
469
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-topic-tags enabled"}
470
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-tag enabled"}
471
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool remove-tag-from-entity enabled"}
472
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool add-tags-to-topic enabled"}
473
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-tags enabled"}
474
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool alter-topic-config enabled"}
475
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-clusters enabled"}
476
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-environments enabled"}
477
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-environment enabled"}
478
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-schemas enabled"}
479
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool get-topic-config enabled"}
480
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-tableflow-topic enabled"}
481
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-tableflow-regions enabled"}
482
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-tableflow-topics enabled"}
483
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-tableflow-topic enabled"}
484
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool update-tableflow-topic enabled"}
485
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-tableflow-topic enabled"}
486
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool create-tableflow-catalog-integration enabled"}
487
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool list-tableflow-catalog-integrations enabled"}
488
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool read-tableflow-catalog-integration enabled"}
489
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool update-tableflow-catalog-integration enabled"}
490
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Tool delete-tableflow-catalog-integration enabled"}
491
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Starting transports: stdio"}
492
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"STDIO transport connected"}
493
- {"level":"info","time":"2025-05-14T16:55:45.911Z","pid":47344,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"All transports started successfully"}
494
- ```
495
-
496
- </details>
497
-
498
625
  #### Example: List All Available Tools
499
626
 
500
627
  ```bash
@@ -516,6 +643,15 @@ delete-connector: Delete an existing connector. Returns success message if delet
516
643
  delete-flink-statements: Make a request to delete a statement.
517
644
  delete-tag: Delete a tag definition from Confluent Cloud.
518
645
  delete-topics: Delete the topic with the given names.
646
+ check-flink-statement-health: Perform an aggregate health check for a Flink SQL statement.
647
+ describe-flink-table: Get full schema details for a Flink table via INFORMATION_SCHEMA.COLUMNS.
648
+ detect-flink-statement-issues: Detect issues for a Flink SQL statement by analyzing status, exceptions, and metrics.
649
+ get-flink-statement-profile: Get Query Profiler data with task graph, metrics, and automated issue detection.
650
+ get-flink-table-info: Get table metadata via INFORMATION_SCHEMA.TABLES.
651
+ list-flink-catalogs: List all catalogs in the Flink environment.
652
+ list-flink-databases: List all databases (schemas) in a Flink catalog via INFORMATION_SCHEMA.SCHEMATA.
653
+ list-flink-tables: List all tables in a Flink database.
654
+ get-flink-statement-exceptions: Retrieve the 10 most recent exceptions for a Flink SQL statement.
519
655
  get-topic-config: Retrieve configuration details for a specific Kafka topic.
520
656
  list-clusters: Get all clusters in the Confluent Cloud environment
521
657
  list-connectors: Retrieve a list of "names" of the active connectors. You can then make a read request for a specific connector by name.
@@ -532,7 +668,6 @@ remove-tag-from-entity: Remove tag from an entity in Confluent Cloud.
532
668
  search-topics-by-name: List all topics in the Kafka cluster matching the specified name.
533
669
  search-topics-by-tag: List all topics in the Kafka cluster with the specified tag.
534
670
  create-tableflow-topic: Make a request to create a tableflow topic.
535
- create-tableflow-topic: Make a request to create a tableflow topic.
536
671
  list-tableflow-regions: Retrieve a sorted, filtered, paginated list of all tableflow regions.
537
672
  list-tableflow-topics: Retrieve a sorted, filtered, paginated list of all tableflow topics.
538
673
  read-tableflow-topic: Make a request to read a tableflow topic.
@@ -549,60 +684,169 @@ delete-tableflow-catalog-integration: Make a request to delete a tableflow catal
549
684
 
550
685
  > **Tip:** The allow-list is applied before the block-list. If neither is provided, all tools are enabled by default.
551
686
 
687
+ ## Flink Example Workflows
688
+
689
+ Examples of how the Flink tools (see [Available Tools](#available-tools)) work together in practice.
690
+
691
+ #### Deduplication Workflow
692
+
693
+ ```
694
+ User: "I want to deduplicate events from my_topic"
695
+ ↓
696
+ Claude: Uses describe-flink-table → gets schema (event_id, user_id, ...)
697
+ ↓
698
+ Claude: "Which field should I deduplicate on?"
699
+ ↓
700
+ User: "event_id"
701
+ ↓
702
+ Claude: Generates SQL using ROW_NUMBER() pattern
703
+ ↓
704
+ Claude: Uses create-flink-statement → submits query
705
+ ↓
706
+ Claude: Uses check-flink-statement-health → monitors status
707
+ ↓
708
+ Claude: "Running successfully!"
709
+ ```
710
+
711
+ #### Debugging a Failed Statement
712
+
713
+ ```
714
+ User: "My statement xyz is failing. What's wrong?"
715
+ ↓
716
+ Claude: Uses get-flink-statement-exceptions → gets error details
717
+ ↓
718
+ Claude: Uses detect-flink-statement-issues → analyzes status, exceptions, metrics
719
+ ↓
720
+ Claude: Uses get-flink-statement-profile → gets task-level metrics
721
+ ↓
722
+ Claude: "The statement has high backpressure on task 'Sink'. Try increasing parallelism..."
723
+ ```
724
+
725
+ ## Metrics Example Workflows
726
+
727
+ The `list-available-metrics` and `query-metrics` tools work together to let AI assistants monitor your Confluent Cloud resources. The discovery tool ensures the assistant uses valid metric names and filter fields rather than guessing.
728
+
729
+ #### Kafka Topic Throughput
730
+
731
+ ```
732
+ User: "What's the throughput on topic sensor-readings over the last hour?"
733
+ ↓
734
+ Claude: Uses list-available-metrics(resource_type: "kafka") → discovers metric names & filters
735
+ ↓
736
+ Claude: Uses query-metrics(metric: "io.confluent.kafka.server/received_bytes",
737
+ filter: {"metric.topic": "sensor-readings"}) → gets time-series data
738
+ ↓
739
+ Claude: "sensor-readings is receiving ~14.3 KB/min steadily over the last hour."
740
+ ```
741
+
742
+ #### Flink Compute Pool Utilization
743
+
744
+ ```
745
+ User: "How many CFUs is my Flink compute pool using?"
746
+ ↓
747
+ Claude: Uses list-available-metrics(resource_type: "compute_pool") → discovers CFU metrics
748
+ ↓
749
+ Claude: Uses query-metrics(metric: "io.confluent.flink/compute_pool_utilization/current_cfus",
750
+ filter: {"resource.compute_pool.id": "lfcp-..."}, granularity: "PT1H",
751
+ interval: "<7-day range>") → gets usage trend
752
+ ↓
753
+ Claude: "Your compute pool is using 1 CFU consistently."
754
+ ```
755
+
756
+ #### Consumer Lag Monitoring
757
+
758
+ ```
759
+ User: "Is there any consumer lag on the sensor-readings topic?"
760
+ ↓
761
+ Claude: Uses query-metrics(metric: "io.confluent.kafka.server/consumer_lag_offsets",
762
+ filter: {"metric.topic": "sensor-readings"},
763
+ group_by: ["metric.consumer_group_id"]) → gets lag per consumer group
764
+ ↓
765
+ Claude: "Consumer group 'analytics' has 1,200 offsets of lag."
766
+ ```
767
+
768
+ > **Note:** Kafka server metrics (e.g., `io.confluent.kafka.server/received_bytes`) require `CONFLUENT_CLOUD_API_KEY` and `CONFLUENT_CLOUD_API_SECRET`. The `KAFKA_CLUSTER_ID` environment variable is auto-injected as a filter when querying Kafka metrics. Flink compute pool metrics report at hourly granularity, so queries may need a wider time window than the default 1 hour.
769
+
552
770
  ## Developer Guide
553
771
 
554
772
  ### Project Structure
555
773
 
556
774
  ```sh
557
775
  /
558
- ├── src/ # Source code
559
- │ ├── confluent/ # Confluent integration (API clients, etc.)
560
- │ │ └── tools/ # Tool implementations
561
- │ ├── mcp/ # MCP protocol and transport logic
562
- │ │ └── transports/
563
- │ └── ... # Other server logic, utilities, etc.
564
- ├── dist/ # Compiled output
565
- ├── openapi.json # OpenAPI specification for Confluent Cloud
566
- ├── .env # Environment variables (example - should be copied and filled)
567
- ├── README.md # This file
568
- └── package.json # Node.js project metadata and dependencies
776
+ ├── src/ # Source code
777
+ │ ├── index.ts # Main entry point
778
+ │ ├── cli.ts # CLI argument parsing
779
+ │ ├── env.ts # Environment initialization
780
+ │ ├── env-schema.ts # Environment variable schema (Zod)
781
+ │ ├── logger.ts # Logger configuration
782
+ │ ├── confluent/ # Confluent integration
783
+ │ │ ├── client-manager.ts # API client management
784
+ │ │ ├── schema-registry-helper.ts
785
+ │ │ └── tools/
786
+ │ │ ├── base-tools.ts # Base handler class
787
+ │ │ ├── tool-factory.ts # Tool registry
788
+ │ │ ├── tool-name.ts # Tool name enum
789
+ │ │ └── handlers/
790
+ │ │ ├── billing/ # Billing tools
791
+ │ │ ├── catalog/ # Catalog & tag tools
792
+ │ │ ├── clusters/ # Cluster tools
793
+ │ │ ├── connect/ # Connector tools
794
+ │ │ ├── environments/ # Environment tools
795
+ │ │ ├── flink/ # Flink SQL, catalog & diagnostics tools
796
+ │ │ ├── kafka/ # Kafka topic & message tools
797
+ │ │ ├── metrics/ # Telemetry API metrics tools
798
+ │ │ ├── schema/ # Schema Registry tools
799
+ │ │ ├── search/ # Search tools
800
+ │ │ └── tableflow/ # Tableflow topic & catalog tools
801
+ │ └── mcp/ # MCP protocol and transport logic
802
+ │ └── transports/
803
+ │ ├── http.ts # HTTP transport
804
+ │ ├── sse.ts # SSE transport
805
+ │ ├── stdio.ts # STDIO transport
806
+ │ ├── auth.ts # Authentication middleware
807
+ │ └── manager.ts # Transport manager
808
+ ├── dist/ # Compiled output
809
+ ├── openapi.json # OpenAPI specification for Confluent Cloud
810
+ ├── .env.example # Example environment variables
811
+ ├── README.md # This file
812
+ └── package.json # Node.js project metadata and dependencies
569
813
  ```
570
814
 
571
815
  ### Building and Running
572
816
 
573
817
  1. **Install Dependencies:**
574
818
 
575
- ```bash
576
- npm install
577
- ```
819
+ ```bash
820
+ npm install
821
+ ```
578
822
 
579
823
  2. **Development Mode (watch for changes):**
580
824
 
581
- ```bash
582
- npm run dev
583
- ```
825
+ ```bash
826
+ npm run dev
827
+ ```
584
828
 
585
- This command compiles the TypeScript code to JavaScript and automatically rebuilds when changes are detected in the `src/` directory.
829
+ This command compiles the TypeScript code to JavaScript and automatically rebuilds when changes are detected in the `src/` directory.
586
830
 
587
831
  3. **Production Build (one-time compilation):**
588
832
 
589
- ```bash
590
- npm run build
591
- ```
833
+ ```bash
834
+ npm run build
835
+ ```
592
836
 
593
837
  4. **Start the Server:**
594
838
 
595
- ```bash
596
- npm run start
597
- ```
598
-
839
+ ```bash
840
+ npm run start
841
+ ```
599
842
 
600
843
  ### Docker
601
844
 
602
845
  #### Prerequisites
846
+
603
847
  Before you begin, ensure you have the following installed on your system:
604
848
 
605
- Docker Desktop (or Docker Engine and Docker Compose): https://www.docker.com/products/docker-desktop
849
+ Docker Desktop (or Docker Engine and Docker Compose): <https://www.docker.com/products/docker-desktop>
606
850
 
607
851
  ##### Environment Variables
608
852
 
@@ -612,67 +856,67 @@ The MCP server requires several environment variables to connect to Confluent Cl
612
856
 
613
857
  Here's how to build your Docker image and run it in different modes.
614
858
 
615
- 1. **Navigate to your project directory.** Open your terminal or command prompt and change to the directory containing the `Dockerfile`.
859
+ 1. **Navigate to your project directory.** Open your terminal or command prompt and change to the directory containing the `Dockerfile`.
616
860
 
617
- ```bash
618
- cd /path/to/repo/mcp-confluent
619
- ```
861
+ ```bash
862
+ cd /path/to/repo/mcp-confluent
863
+ ```
620
864
 
621
- 2. **Build the Docker image.**
865
+ 2. **Build the Docker image.**
622
866
 
623
- This command creates the `mcp-server` image based on the `Dockerfile` in the current directory.
867
+ This command creates the `mcp-server` image based on the `Dockerfile` in the current directory.
624
868
 
625
- ```bash
626
- docker build -t mcp-server .
627
- ```
869
+ ```bash
870
+ docker build -t mcp-server .
871
+ ```
628
872
 
629
- 3. **Run the container**
873
+ 3. **Run the container**
874
+ - `--rm`: **Automatically removes the container** when it exits. This helps keep your system clean.
875
+ - `-i`: Keeps **STDIN open** (runs the server using stdio transport by default).
876
+ - `-d`: Runs the container in **detached mode** (in the background).
877
+ - `-p 8080:8080`: **Maps port 8080** on your host machine to port 8080 inside the container. The default HTTP_PORT is 8080; adjust if you've configured a different port.
878
+
879
+ ```bash
880
+ docker run --rm -i -d -p 8080:8080 mcp-server
881
+ ```
630
882
 
631
- * `--rm`: **Automatically removes the container** when it exits. This helps keep your system clean.
632
- * `-i`: Keeps **STDIN open** (runs the server using stdio transport by default).
633
- * `-d`: Runs the container in **detached mode** (in the background).
634
- * `-p 3000:3000`: **Maps port 3000** on your host machine to port 3000 inside the container. Adjust this if your app listens on a different port.
883
+ (Optional)
884
+ - `-t` **Transport Mode** to enable http transport
635
885
 
636
- ```bash
637
- docker run --rm -i -d -p 3000:3000 mcp-server
638
- ```
639
- (Optional)
640
- * `-t` **Transport Mode** to enable http transport
641
- ```bash
642
- docker run --rm -d -p 3000:3000 mcp-server -t http
643
- ```
886
+ ```bash
887
+ docker run --rm -d -p 8080:8080 mcp-server -t http
888
+ ```
644
889
 
645
890
  #### Building and Running with Docker Compose
646
891
 
647
892
  1. **Navigate to the project root:**
648
- Open your terminal or command prompt and change to the directory containing Dockerfile and docker-compose.yml.
893
+ Open your terminal or command prompt and change to the directory containing Dockerfile and docker-compose.yml.
649
894
 
650
- ```bash
651
- cd /path/to/repo/mcp-confluent
652
- ```
895
+ ```bash
896
+ cd /path/to/repo/mcp-confluent
897
+ ```
653
898
 
654
899
  2. **Build and run the service:**
655
- Docker Compose will build the Docker image (if not already built) and start the mcp-server service.
900
+ Docker Compose will build the Docker image (if not already built) and start the mcp-server service.
656
901
 
657
- ```bash
658
- docker compose up --build
659
- ```
902
+ ```bash
903
+ docker compose up --build
904
+ ```
660
905
 
661
- The --build flag ensures that Docker Compose rebuilds the image before starting the container. You can omit this flag on subsequent runs if you haven't changed the Dockerfile or source code.
906
+ The --build flag ensures that Docker Compose rebuilds the image before starting the container. You can omit this flag on subsequent runs if you haven't changed the Dockerfile or source code.
662
907
 
663
- The server will be accessible on http://localhost:3000 (or the port specified in HTTP_PORT in your .env file).
908
+ The server will be accessible on <http://localhost:8080> (or the port specified in HTTP_PORT in your .env file).
664
909
 
665
910
  3. **Stopping the Server**
666
- To stop the running MCP server and remove the containers, press Ctrl+C in the terminal where docker compose up is running.
667
-
668
- Alternatively, in a new terminal from the project root, you can run:
911
+ To stop the running MCP server and remove the containers, press Ctrl+C in the terminal where docker compose up is running.
669
912
 
670
- ```bash
671
- docker compose down
672
- ```
913
+ Alternatively, in a new terminal from the project root, you can run:
673
914
 
674
- This command stops and removes the containers, networks, and volumes created by docker compose up.
915
+ ```bash
916
+ docker compose down
917
+ ```
675
918
 
919
+ This command stops and removes the containers, networks, and volumes created by docker compose up.
676
920
 
677
921
  ### Testing
678
922
 
@@ -685,13 +929,64 @@ For testing MCP servers, you can use [MCP Inspector](https://modelcontextprotoco
685
929
  npx @modelcontextprotocol/inspector node $PATH_TO_PROJECT/dist/index.js --env-file $PATH_TO_PROJECT/.env
686
930
  ```
687
931
 
932
+ ### Local Development with an MCP Client
933
+
934
+ While the [MCP Inspector](#mcp-inspector) is useful for ad-hoc tool testing, this setup lets you develop against a real MCP client (Claude Code, Cursor, etc.) with full server log visibility. By default, MCP clients spawn the server as a child process using stdio transport, which makes server logs difficult to observe. Running the server in HTTP mode gives you direct access to logs while the client interacts with it normally.
935
+
936
+ After building the project (see [Building and Running](#building-and-running)):
937
+
938
+ #### 1. Start the server in HTTP mode
939
+
940
+ ```bash
941
+ npm run start:http -- --disable-auth
942
+ ```
943
+
944
+ > [!WARNING]
945
+ > Never disable authentication in production or when the server is network-accessible.
946
+
947
+ This starts the server on `http://127.0.0.1:8080/mcp` (the defaults for `HTTP_HOST`, `HTTP_PORT`, and `HTTP_MCP_ENDPOINT_PATH`) with authentication disabled for local development.
948
+
949
+ #### 2. Point your MCP client at the running server
950
+
951
+ Instead of the default stdio configuration, configure your assistant's MCP settings to connect via HTTP. For example, in `.mcp.json`:
952
+
953
+ ```json
954
+ {
955
+ "mcpServers": {
956
+ "confluent-dev": {
957
+ "type": "http",
958
+ "url": "http://127.0.0.1:8080/mcp"
959
+ }
960
+ }
961
+ }
962
+ ```
963
+
964
+ This replaces the typical `command`/`args` config that spawns a stdio child process.
965
+
966
+ > [!IMPORTANT]
967
+ > After restarting the MCP server, you may also need to restart or reconnect your MCP client so it picks up the new server process. For example, in Claude Code use the `/mcp` command to reconnect.
968
+
969
+ #### 3. Observe server logs
970
+
971
+ All server logs are written to stderr via pino and will appear directly in the terminal where you started the server. Set `LOG_LEVEL=debug` for more verbose output. To capture logs to a file instead:
972
+
973
+ ```bash
974
+ npm run start:http -- --disable-auth 2>server.log
975
+ ```
976
+
977
+ Then tail in a separate terminal:
978
+
979
+ ```bash
980
+ tail -f server.log
981
+ ```
982
+
688
983
  ### Adding a New Tool
689
984
 
690
985
  1. Add a new enum to the enum class `ToolName`.
691
986
  2. Add your new tool to the handlers map in the `ToolFactory` class.
692
987
  3. Create a new file, exporting the class that extends `BaseToolHandler`.
693
- 1. Implement the `handle` method of the base class.
694
- 2. Implement the `getToolConfig` method of the base class.
988
+ 1. Implement the `handle` method of the base class.
989
+ 2. Implement the `getToolConfig` method of the base class.
695
990
  4. Once satisfied, add it to the set of `enabledTools` in `index.ts`.
696
991
 
697
992
  ### Generating Types
@@ -701,6 +996,22 @@ npx @modelcontextprotocol/inspector node $PATH_TO_PROJECT/dist/index.js --env-f
701
996
  npx openapi-typescript ./openapi.json -o ./src/confluent/openapi-schema.d.ts --empty-objects-unknown
702
997
  ```
703
998
 
999
+ ## Telemetry
1000
+
1001
+ This MCP server collects anonymous usage data to help make improvements. No personally identifiable information is collected. You can opt out by setting `DO_NOT_TRACK=true` in your environment. See [telemetry.md](telemetry.md) for full details on what is collected.
1002
+
1003
+ ## Troubleshooting
1004
+
1005
+ **"Node.js version not supported"** -- This project requires Node.js 22 or later. Check your version with `node -v` and upgrade if needed.
1006
+
1007
+ **Tools not appearing** -- Ensure the required environment variables for those tools are set in your `.env` file. Tools are only enabled when their dependencies are configured. Run `--list-tools` to see which tools are active.
1008
+
1009
+ **Authentication errors on HTTP/SSE** -- Generate an API key with `npx @confluentinc/mcp-confluent --generate-key` and add it to your `.env` file as `MCP_API_KEY`. See [Authentication for HTTP/SSE Transports](#authentication-for-httpsse-transports).
1010
+
1011
+ **Connection refused / port conflicts** -- The default HTTP port is 8080. If it's already in use, set a different port via `HTTP_PORT` in your `.env` file.
1012
+
1013
+ **Tableflow authorization errors** -- Tableflow tools require specific IAM permissions in your cloud environment. See [Prerequisites & Setup for Tableflow Commands](#prerequisites--setup-for-tableflow-commands).
1014
+
704
1015
  ### Contributing
705
1016
 
706
- Bug reports and feedback is appreciated in the form of Github Issues. For guidelines on contributing please see [CONTRIBUTING.md](CONTRIBUTING.MD)
1017
+ Bug reports and feedback is appreciated in the form of Github Issues. For guidelines on contributing please see [CONTRIBUTING.md](CONTRIBUTING.md)