@confluentinc/mcp-confluent 1.2.2 → 1.4.0

package/README.md

@@ -3,250 +3,251 @@
 [![npm version](https://img.shields.io/npm/v/@confluentinc/mcp-confluent.svg)](https://www.npmjs.com/package/@confluentinc/mcp-confluent)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-An open-source [MCP server](https://modelcontextprotocol.io/) that enables AI assistants to interact with Confluent Cloud and Confluent Local through natural language. It provides 50+ 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.
+An open-source [MCP server](https://modelcontextprotocol.io/) that enables AI assistants to interact with Confluent Cloud, Confluent Platform, and standalone Apache Kafka deployments through natural language.
+It provides 50+ 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.
 
 ## Quick Start
 
-> **Prerequisites:** [Node.js 22+](https://nodejs.org/). If you want to interact with [Confluent Cloud](https://confluent.cloud/), you need to create an account first.
+> **Prerequisites:** [Node.js 22+](https://nodejs.org/).
+> If you want to interact with [Confluent Cloud](https://confluent.cloud/), you need to create an account first.
+
+1. Generate a quick `config.yaml` file in your project root:
+
+```bash
+npx @confluentinc/mcp-confluent --init-config
+```
+
+2. Edit the `config.yaml` file with your connection details, then:
 
 ```bash
-# Install and run
-npx -y @confluentinc/mcp-confluent -e /path/to/.env
+npx @confluentinc/mcp-confluent --config ./config.yaml
 ```
 
-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-mcp-clients) for integration with your preferred AI tool.
+See [Getting Started](#getting-started) for full setup instructions and [Configuring MCP Clients](#configuring-mcp-clients) for integration with your preferred AI tool.
 
 ## Table of Contents
 
 - [Quick Start](#quick-start)
 - [Available Tools](#available-tools)
+  - [Always Available](#always-available-tools)
   - [Confluent Cloud](#available-tools-for-confluent-cloud)
-  - [Confluent Local](#available-tools-for-confluent-local)
-- [User Guide](#user-guide)
-  - [Getting Started](#getting-started)
-  - [Configuration](#configuration)
-  - [Authentication for HTTP/SSE Transports](#authentication-for-httpsse-transports)
-  - [Usage](#usage)
-  - [CLI Usage](#cli-usage)
-  - [Configuring MCP Clients](#configuring-mcp-clients)
+  - [Local deployments](#available-tools-for-local-deployments)
+- [Using with Confluent Platform](#using-with-confluent-platform)
+- [Getting Started](#getting-started)
+- [Configuration](#configuration)
+- [OAuth Authentication for Confluent Cloud](#oauth-authentication-for-confluent-cloud)
+- [CLI Usage](#cli-usage)
+- [Configuring MCP Clients](#configuring-mcp-clients)
 - [Telemetry](#telemetry)
 - [Troubleshooting](#troubleshooting)
 - [Contributing](#contributing)
 
 ## Available Tools
 
-Only the tools whose required environment variables are configured will be enabled. You can also list all available tools via the CLI:
+Tools are auto-enabled based on which service blocks are present in your resolved configuration; see [CONFIGURATION.md](CONFIGURATION.md#tool-enablement-which-block-lights-up-what) for the full block-to-tool mapping.
+
+You can list all available tools via the CLI:
 
 ```bash
 npx -y @confluentinc/mcp-confluent --list-tools
 ```
 
+### Always-Available Tools
+
+These tools need no service blocks or authentication — they're enabled even on a bare config, regardless of which deployment the rest of your config targets.
+
+| Category          | Tools                                         | Description                                               |
+| ----------------- | --------------------------------------------- | --------------------------------------------------------- |
+| **Documentation** | `search-product-docs`, `get-product-doc-page` | Search Confluent product docs and fetch full page content |
+| **Diagnostics**   | `explain-disabled-tools`                      | Explain why specific tools are absent from `tools/list`   |
+
 ### Available Tools for Confluent Cloud
 
-These tools require endpoints and authentication against specific Confluent Cloud components. Refer to [`.env.example`](.env.example) for the full set of configuration variables.
-
-| Category                    | Tools                                                                                                                                                                                               | Description                                                       |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| **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 |
-| **Flink SQL**               | `create-flink-statement`, `list-flink-statements`, `read-flink-statement`, `delete-flink-statements`, `get-flink-statement-exceptions`                                                              | Create and manage Flink SQL statements                            |
-| **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              |
-| **Flink Diagnostics**       | `check-flink-statement-health`, `detect-flink-statement-issues`, `get-flink-statement-profile`                                                                                                      | Health checks, issue detection, and query profiling               |
-| **Connectors**              | `list-connectors`, `read-connector`, `create-connector`, `delete-connector`                                                                                                                         | Manage Kafka Connect connectors                                   |
-| **Schema Registry**         | `list-schemas`, `delete-schema`                                                                                                                                                                     | List, inspect, and delete data schemas                            |
-| **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                             |
-| **Environments & Clusters** | `list-environments`, `read-environment`, `list-clusters`                                                                                                                                            | Discover Confluent Cloud resources                                |
-| **Tableflow**               | `create-tableflow-topic`, `list-tableflow-topics`, `read-tableflow-topic`, `update-tableflow-topic`, `delete-tableflow-topic`, `list-tableflow-regions`                                             | Manage Tableflow-enabled topics                                   |
-| **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)            |
-| **Metrics**                 | `list-available-metrics`, `query-metrics`                                                                                                                                                           | Discover and query Confluent Cloud operational metrics            |
-| **Billing**                 | `list-billing-costs`                                                                                                                                                                                | Query billing and cost data                                       |
-
-### Available Tools for Confluent Local
-
-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.
-
-```properties
-# minimal .env for local development
-BOOTSTRAP_SERVERS="localhost:9092"
-SCHEMA_REGISTRY_ENDPOINT="http://localhost:8081"
+These tools require endpoints and authentication against specific Confluent Cloud components.
+Refer to [`config.example.yaml`](config.example.yaml) for the full set of configuration variables.
+Categories marked with ¹ also work with [OAuth authentication](#oauth-authentication-for-confluent-cloud) — sign in via your browser instead of provisioning API keys.
+
+| Category                                     | Tools                                                                                                                                                                                                                                                                                                                                        | Description                                                                                |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **Kafka** ¹                                  | `list-topics`, `create-topics`, `delete-topics`, `produce-message`, `consume-messages`, `list-consumer-groups`, `describe-consumer-group`, `get-consumer-group-lag`, `alter-topic-config`, `get-topic-config`                                                                                                                                | Manage topics, produce/consume messages, inspect consumer groups, configure topic settings |
+| **Flink SQL**                                | `create-flink-statement`, `list-flink-statements`, `read-flink-statement`, `delete-flink-statements`, `get-flink-statement-exceptions`                                                                                                                                                                                                       | Create and manage Flink SQL statements                                                     |
+| **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                                       |
+| **Flink Diagnostics**                        | `check-flink-statement-health`, `detect-flink-statement-issues`, `get-flink-statement-profile`                                                                                                                                                                                                                                               | Health checks, issue detection, and query profiling                                        |
+| **Connectors**                               | `list-connectors`, `get-connector-config`, `get-connector-offsets`, `get-connector-status`, `get-connector-tasks`, `get-connector-error-summary`, `get-connector-error-recommendations`, `get-connector-logs`, `create-connector`, `delete-connector`, `pause-connector`, `resume-connector`, `restart-connector`, `update-connector-config` | Inspect and manage Kafka Connect connectors                                                |
+| **Schema Registry** ¹                        | `list-schemas`, `delete-schema`                                                                                                                                                                                                                                                                                                              | List, inspect, and delete data schemas                                                     |
+| **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                                                      |
+| **Organizations, Environments & Clusters** ¹ | `list-organizations`, `list-environments`, `read-environment`, `list-clusters`                                                                                                                                                                                                                                                               | Discover Confluent Cloud resources                                                         |
+| **Tableflow**                                | `create-tableflow-topic`, `list-tableflow-topics`, `read-tableflow-topic`, `update-tableflow-topic`, `delete-tableflow-topic`, `list-tableflow-regions`                                                                                                                                                                                      | Manage Tableflow-enabled topics                                                            |
+| **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)                                     |
+| **Metrics**                                  | `list-available-metrics`, `query-metrics`                                                                                                                                                                                                                                                                                                    | Discover and query Confluent Cloud operational metrics                                     |
+| **Billing** ¹                                | `list-billing-costs`                                                                                                                                                                                                                                                                                                                         | Query billing and cost data                                                                |
+
+¹ Also available under OAuth — see [OAuth Authentication for Confluent Cloud](#oauth-authentication-for-confluent-cloud) for setup and caveats.
+Categories not marked currently require a `direct` connection with static API keys; OAuth migration is in progress.
+
+### Available Tools for local deployments
+
+These tools only require Kafka or Schema Registry endpoints - no Confluent Cloud API key/secret is needed.
+Ideal for local development with self-managed clusters, including Confluent Platform.
+
+```yaml
+# minimal config.yaml for local development
+connections:
+  local:
+    type: direct
+    kafka:
+      bootstrap_servers: "localhost:9092"
+    schema_registry:
+      endpoint: "http://localhost:8081"
 ```
 
-| Category            | Tools                                                                                  | Description                             |
-| ------------------- | -------------------------------------------------------------------------------------- | --------------------------------------- |
-| **Kafka**           | `list-topics`, `create-topics`, `delete-topics`, `produce-message`, `consume-messages` | Manage topics, produce/consume messages |
-| **Schema Registry** | `list-schemas`, `delete-schema`                                                        | List, inspect, and delete data schemas  |
+Ready-to-use variants live in [`sample_configs/`](sample_configs/).
 
-## User Guide
+| Category            | Tools                                                                                                                                                               | Description                                                      |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| **Kafka**           | `list-topics`, `create-topics`, `delete-topics`, `produce-message`, `consume-messages`, `list-consumer-groups`, `describe-consumer-group`, `get-consumer-group-lag` | Manage topics, produce/consume messages, inspect consumer groups |
+| **Schema Registry** | `list-schemas`, `delete-schema`                                                                                                                                     | List, inspect, and delete data schemas                           |
 
-### Getting Started
+## Using with Confluent Platform
 
-#### Prerequisites
+`mcp-confluent` runs against a self-managed Confluent Platform (CP) cluster the same way it runs against any local Kafka + Schema Registry deployment: point a `direct` connection at your brokers and Schema Registry.
+A CP connection exposes the same tools as any other local deployment — see [Available Tools for local deployments](#available-tools-for-local-deployments).
+The Confluent Cloud tools (Flink, Tableflow, Billing, Metrics, and the rest) require a Confluent Cloud account and stay disabled on CP.
+The only differences from a `localhost:9092` setup are authentication and TLS.
 
-- **Node.js 22 or later** -- we recommend using [NVM](https://github.com/nvm-sh/nvm) to manage versions:
-  ```bash
-  nvm install 22
-  nvm use 22
-  ```
-- A **Confluent Cloud** account with appropriate API keys
-
-#### Setup
-
-1. **Create a `.env` file:** Copy the provided `.env.example` file to `.env` in the root of your project:
-   ```bash
-   cp .env.example .env
-   ```
-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.
-
-### Configuration
-
-You can configure the MCP server using the following environment variables:
-
-| Variable                      | Description                                                                                                                                                                                                                                                       | Default Value                           | Required |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------- |
-| HTTP_HOST                     | Host to bind for HTTP transport. Defaults to localhost only for security.                                                                                                                                                                                         | "127.0.0.1"                             | Yes      |
-| HTTP_MCP_ENDPOINT_PATH        | HTTP endpoint path for MCP transport (e.g., '/mcp') (string)                                                                                                                                                                                                      | "/mcp"                                  | Yes      |
-| HTTP_PORT                     | Port to use for HTTP transport (number (min: 0))                                                                                                                                                                                                                  | 8080                                    | Yes      |
-| LOG_LEVEL                     | Log level for application logging (trace, debug, info, warn, error, fatal)                                                                                                                                                                                        | "info"                                  | Yes      |
-| MCP_API_KEY                   | API key for HTTP/SSE authentication. Generate using `--generate-key`. Required when auth is enabled.                                                                                                                                                              |                                         | No\*     |
-| MCP_AUTH_DISABLED             | Disable authentication for HTTP/SSE transports. WARNING: Only use in development environments.                                                                                                                                                                    | false                                   | No       |
-| MCP_ALLOWED_HOSTS             | Comma-separated list of allowed Host header values for DNS rebinding protection.                                                                                                                                                                                  | "localhost,127.0.0.1"                   | No       |
-| SSE_MCP_ENDPOINT_PATH         | SSE endpoint path for establishing SSE connections (e.g., '/sse', '/events') (string)                                                                                                                                                                             | "/sse"                                  | Yes      |
-| SSE_MCP_MESSAGE_ENDPOINT_PATH | SSE message endpoint path for receiving messages (e.g., '/messages', '/events/messages') (string)                                                                                                                                                                 | "/messages"                             | Yes      |
-| 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       |
-| CONFLUENT_CLOUD_API_KEY       | Master API key for Confluent Cloud platform administration, enabling management of resources across your organization (string (min: 1))                                                                                                                           |                                         | No       |
-| CONFLUENT_CLOUD_API_SECRET    | Master API secret paired with CONFLUENT_CLOUD_API_KEY for comprehensive Confluent Cloud platform administration (string (min: 1))                                                                                                                                 |                                         | No       |
-| CONFLUENT_CLOUD_REST_ENDPOINT | Base URL for Confluent Cloud's REST API services (default)                                                                                                                                                                                                        | https://api.confluent.cloud             | No       |
-| FLINK_API_KEY                 | Authentication key for accessing Confluent Cloud's Flink services, including compute pools and SQL statement management (string (min: 1))                                                                                                                         |                                         | No       |
-| FLINK_API_SECRET              | Secret token paired with FLINK_API_KEY for authenticated access to Confluent Cloud's Flink services (string (min: 1))                                                                                                                                             |                                         | No       |
-| FLINK_COMPUTE_POOL_ID         | Unique identifier for the Flink compute pool, must start with 'lfcp-' prefix (string)                                                                                                                                                                             |                                         | No       |
-| FLINK_DATABASE_NAME           | Name of the associated Kafka cluster used as a database reference in Flink SQL operations (string (min: 1))                                                                                                                                                       |                                         | No       |
-| FLINK_ENV_ID                  | Unique identifier for the Flink environment, must start with 'env-' prefix (string)                                                                                                                                                                               |                                         | No       |
-| FLINK_ENV_NAME                | Human-readable name for the Flink environment used for identification and display purposes (string (min: 1))                                                                                                                                                      |                                         | No       |
-| FLINK_ORG_ID                  | Organization identifier within Confluent Cloud for Flink resource management (string (min: 1))                                                                                                                                                                    |                                         | No       |
-| FLINK_REST_ENDPOINT           | Base URL for Confluent Cloud's Flink REST API endpoints used for SQL statement and compute pool management (string)                                                                                                                                               |                                         | No       |
-| KAFKA_API_KEY                 | Authentication credential (username) required to establish secure connection with the Kafka cluster (string (min: 1))                                                                                                                                             |                                         | No       |
-| KAFKA_API_SECRET              | Authentication credential (password) paired with KAFKA_API_KEY for secure Kafka cluster access (string (min: 1))                                                                                                                                                  |                                         | No       |
-| KAFKA_CLUSTER_ID              | Unique identifier for the Kafka cluster within Confluent Cloud ecosystem (string (min: 1))                                                                                                                                                                        |                                         | No       |
-| KAFKA_ENV_ID                  | Environment identifier for Kafka cluster, must start with 'env-' prefix (string)                                                                                                                                                                                  |                                         | No       |
-| KAFKA_REST_ENDPOINT           | REST API endpoint for Kafka cluster management and administration (string)                                                                                                                                                                                        |                                         | No       |
-| SCHEMA_REGISTRY_API_KEY       | Authentication key for accessing Schema Registry services to manage and validate data schemas (string (min: 1))                                                                                                                                                   |                                         | No       |
-| SCHEMA_REGISTRY_API_SECRET    | Authentication secret paired with SCHEMA_REGISTRY_API_KEY for secure Schema Registry access (string (min: 1))                                                                                                                                                     |                                         | No       |
-| SCHEMA_REGISTRY_ENDPOINT      | URL endpoint for accessing Schema Registry services to manage data schemas (string)                                                                                                                                                                               |                                         | No       |
-| TABLEFLOW_API_KEY             | Authentication key for accessing Confluent Cloud's Tableflow services (string (min: 1))                                                                                                                                                                           |                                         | No       |
-| TABLEFLOW_API_SECRET          | Authentication secret paired with TABLEFLOW_API_KEY for secure Tableflow access (string (min: 1))                                                                                                                                                                 |                                         | No       |
-| TELEMETRY_ENDPOINT            | Base URL for Confluent Cloud Telemetry API (metrics)                                                                                                                                                                                                              | "https://api.telemetry.confluent.cloud" | No       |
-| 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       |
-| 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       |
-| DO_NOT_TRACK                  | Set to `true` to opt out of anonymous telemetry data collection. See [Telemetry](#telemetry) for details.                                                                                                                                                        |                                         | No       |
-
-#### Prerequisites & Setup for Tableflow Commands
-
-In order to leverage **Tableflow commands** to interact with your data ecosystem and successfully execute these Tableflow commands and manage resources (e.g., interacting with data storage like AWS S3 and metadata catalogs like AWS Glue), certain **IAM (Identity and Access Management) permissions** and configurations are essential.
-
-It is crucial to set up the necessary roles and policies in your cloud environment (e.g., AWS) and link them correctly within Confluent Cloud. This ensures your Flink SQL cluster, which powers Tableflow, has the required authorization to perform operations on your behalf.
-
-Please refer to the following Confluent Cloud documentation for detailed instructions on setting up these permissions and integrating with custom storage and Glue:
-
-- **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](https://docs.confluent.io/cloud/current/topics/tableflow/get-started/quick-start-custom-storage-glue.html)
-
-Ensuring these prerequisites are met will prevent authorization errors when the `mcp-server` attempts to provision or manage Tableflow-enabled tables.
-
-### Authentication for HTTP/SSE Transports
-
-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**.
-
-#### Generating an API Key
-
-Generate a secure API key using the built-in utility:
+### Sample YAML config
+
+[`sample_configs/confluent-platform.yaml`](sample_configs/confluent-platform.yaml) is a copy-pasteable starter.
+It assumes PLAIN over SASL_SSL for Kafka and HTTP Basic Auth for Schema Registry.
+Customize the broker and Schema Registry URLs, and inject credentials via the `${KAFKA_API_KEY}` / `${KAFKA_API_SECRET}` / `${SCHEMA_REGISTRY_API_KEY}` / `${SCHEMA_REGISTRY_API_SECRET}` environment variables.
+If your cluster uses SCRAM or another SASL mechanism, override `security.protocol` and `sasl.mechanisms` through the `kafka.extra_properties` map in that file.
+
+### TLS trust (internal CAs)
+
+CP clusters frequently sit behind an internal CA.
+If you see TLS handshake failures against the broker or Schema Registry, point Node at your CA bundle when starting the server:
 
 ```bash
-npx @confluentinc/mcp-confluent --generate-key
+NODE_EXTRA_CA_CERTS=/path/to/internal-ca.pem npm run start -- --config path/to/config.yaml
 ```
 
-This will output a 64-character key generated using secure cryptography:
+### End-to-end smoke test
 
-```
-Generated MCP API Key:
-================================================================
-a1b2c3d4e5f6...your-64-char-key-here...
-================================================================
+A docker-compose stack ([`docker-compose.cp-test.yml`](docker-compose.cp-test.yml)) brings up a local CP Kafka (KRaft, SASL_PLAINTEXT/PLAIN) plus an unauthenticated Schema Registry.
+The matching integration tests are tagged `@cp` and live next to their handlers as `*.cp.integration.test.ts`:
 
+```bash
+docker compose -f docker-compose.cp-test.yml up -d
+# Wait ~30s for Kafka + SR to become ready, then:
+CP_KAFKA_USERNAME=mcp CP_KAFKA_PASSWORD=mcp-secret \
+  npm run test:integration -- --tags-filter=@cp
+docker compose -f docker-compose.cp-test.yml down -v
 ```
 
-#### Configuring Authentication
+The tests skip cleanly when those env vars are unset, so `npm run test:unit` and a default `npm run test:integration` against your real Confluent Cloud account are unaffected if you don't have the docker stack running.
 
-Add the generated key to your `.env` file:
+## Getting Started
 
-```properties
-# MCP Server Authentication (required for HTTP/SSE transports)
-MCP_API_KEY=your-generated-64-char-key-here
-```
+### Prerequisites
+
+- **Node.js 22 or later** -- we recommend using [NVM](https://github.com/nvm-sh/nvm) to manage versions:
+  ```bash
+  nvm install 22
+  nvm use 22
+  ```
+- A local environment with Kafka or Schema Registry running, or a **Confluent Cloud** account with appropriate API keys or login credentials if [using OAuth to authenticate](#oauth-authentication-for-confluent-cloud).
+
+### General Setup Steps
+
+This MCP server is designed to be used with various MCP clients, such as Claude Desktop, Copilot, or Goose CLI/Desktop.
+The specific configuration and interaction will depend on the client you are using.
+
+The MCP server can authenticate to Confluent Cloud via **OAuth (PKCE)** in addition to static API keys defined in the YAML config.
+See [OAuth Authentication For Confluent Cloud](#oauth-authentication-for-confluent-cloud) for more details.
 
-#### Making Authenticated Requests
+The general steps to configure (if not using OAuth) and run this MCP are:
 
-Include the API key in the `cflt-mcp-api-Key` header for all HTTP/SSE requests:
+1. **Create a configuration file:** Copy the provided [`config.yaml` example](https://github.com/confluentinc/mcp-confluent/blob/main/config.example.yaml) file to the root of your project.
+   You can use the CLI to bootstrap one in your current directory — no git checkout required:
 
 ```bash
-curl -H "cflt-mcp-api-Key: your-api-key" http://localhost:8080/mcp
+npx @confluentinc/mcp-confluent --init-config
 ```
 
-#### DNS Rebinding Protection
+2. **Populate the file:** Fill in the necessary values for your Confluent Cloud environment.
+   See [CONFIGURATION.md](CONFIGURATION.md) for the full reference; only fill in the service blocks you need (each one enables a group of tools).
 
-The server includes additional protections against DNS rebinding attacks:
+3. **Start the Server:** You can run the MCP server in one of two ways:
+   - **From source:** Follow the instructions in the [Contributing Guide](CONTRIBUTING.md) to build and run the server from source.
+     This typically involves:
+     - Installing dependencies (`npm install`)
+     - Building the project (`npm run build` or `npm run dev`)
+   - **With npx:** You can start the server directly using npx, no build required:
 
-- **Host Header Validation**: Only requests with allowed Host headers are accepted
+     ```bash
+     npx @confluentinc/mcp-confluent --config /path/to/myconfig.yaml
+     ```
 
-Configure allowed hosts if needed:
+4. **Configure your MCP Client:** Each client (e.g., Claude, Goose) will have its own way of specifying the MCP server's address and any required credentials.
+   You'll need to [configure your client](#configuring-mcp-clients) to connect to the address where this server is running (likely `localhost` with a specific port).
+   The port the server runs on is set via `server.http.port` in `config.yaml`.
 
-```properties
-# Allow additional hosts (comma-separated)
-MCP_ALLOWED_HOSTS=localhost,127.0.0.1,myhost.local
-```
+5. **Start your 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 resources on your behalf.
 
-#### Additional security to prevent internet exposure of MCP server
+6. **Interact with your resources through the Client:** Once the client is connected and configured, you can use the client's interface to interact with Confluent Cloud or local resources.
+   The client will send requests to this MCP server, which will then interact with the available connections on your behalf.
 
-- **Localhost Binding**: Server binds to `127.0.0.1` by default (not `0.0.0.0`)
+## Configuration
 
-#### Disabling Authentication (Development Only)
+The full configuration reference — YAML schema, every service block, env-var interpolation, OAuth and HTTP/SSE auth setup, the (deprecated) legacy env-var table, and tool-to-block mapping — lives in [CONFIGURATION.md](CONFIGURATION.md).
 
-For local development, you can disable authentication:
+> **Compatibility note.** This release ships full parity between YAML (`-c config.yaml`) and the legacy env-var path (`-e config.env`) for a single connection.
+> The env-var-only path will emit a startup warning in a near-future release and be removed a release or two later.
+> Multi-connection support (next release) will be YAML-only.
+> See [CONFIGURATION.md → Two paths, one configuration](CONFIGURATION.md#two-paths-one-configuration).
 
-```bash
-# Via CLI flag
-npx @confluentinc/mcp-confluent -e .env --transport http --disable-auth
+### Prerequisites & setup for Tableflow commands
 
-# Or via environment variable
-MCP_AUTH_DISABLED=true
-```
+Tableflow tools interact with cloud storage (e.g. AWS S3) and a metadata catalog (e.g. AWS Glue) on your behalf via the Flink runtime in Confluent Cloud.
+The Flink runtime needs IAM permissions on your cloud account, and those have to be granted and linked into Confluent Cloud before any Tableflow tool will succeed.
 
-> [!WARNING]
-> Never disable authentication in production or when the server is network-accessible.
+Follow the **[Tableflow quick start with custom storage & Glue](https://docs.confluent.io/cloud/current/topics/tableflow/get-started/quick-start-custom-storage-glue.html)** to set up the roles, policies, and provider integrations.
+Skipping this step leads to authorization errors when mcp-confluent tries to provision or manage Tableflow-enabled tables.
 
-### Usage
+## OAuth Authentication for Confluent Cloud
 
-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:
+The MCP server can authenticate to Confluent Cloud via **OAuth (PKCE)** instead of static API keys.
+On the first tool call that needs Confluent access, the server opens your browser to the Confluent Cloud sign-in page; subsequent tool calls reuse the resulting session.
+No API keys to provision.
 
-1. **Start the Server:** You can run the MCP server in one of two ways:
-   - **From source:** Follow the instructions in the [Contributing Guide](CONTRIBUTING.md) to build and run the server from source. This typically involves:
-     - Installing dependencies (`npm install`)
-     - Building the project (`npm run build` or `npm run dev`)
-   - **With npx:** You can start the server directly using npx (no build required):
+### Setup
 
-     ```bash
-     npx -y @confluentinc/mcp-confluent -e /path/to/confluent-mcp-server/.env
-     ```
+```bash
+npx @confluentinc/mcp-confluent --init-oauth-config
+# edit ./config.yaml if needed, then:
+npx @confluentinc/mcp-confluent --config ./config.yaml
+```
+
+`--init-oauth-config` drops a starter [`config.oauth.example.yaml`](config.oauth.example.yaml) into `./config.yaml`.
+The whole file is essentially:
 
-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.
+```yaml
+connections:
+  ccloud-oauth:
+    type: oauth
+```
 
-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.
+See [CONFIGURATION.md → Authentication modes](CONFIGURATION.md#authentication-modes) for the full schema and ergonomics.
 
-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.
+The ¹-marked categories in [Available Tools for Confluent Cloud](#available-tools-for-confluent-cloud) work under OAuth today; everything else still needs a `direct` connection with static API keys.
 
-### CLI Usage
+## CLI Usage
 
-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.
+The MCP server provides a flexible command line interface (CLI) for advanced control.
+The CLI lets you pick the config file, transports, and fine-tune which tools are enabled or blocked.
 
-#### Basic Usage
+### Basic Usage
 
 You can view all CLI options and help with:
 
@@ -272,7 +273,6 @@ Options:
   --allow-tools-file <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>        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).
   --disable-auth                   Disable authentication for HTTP/SSE transports. WARNING: Only use in development environments.
   --allowed-hosts <hosts>          Comma-separated list of allowed Host header values for DNS rebinding protection.
   --generate-key                   Generate a secure API key for MCP_API_KEY and print it to stdout, then exit.
@@ -281,10 +281,10 @@ Options:
 
 </details>
 
-#### Example: Deploy using all transports
+### Example: Deploy using all transports
 
 ```bash
-npx @confluentinc/mcp-confluent -e .env --transport http,sse,stdio
+npx @confluentinc/mcp-confluent -c config.yaml --transport http,sse,stdio
 ```
 
 <details>
@@ -303,31 +303,31 @@ npx @confluentinc/mcp-confluent -e .env --transport http,sse,stdio
 
 </details>
 
-#### Example: Allow Only Specific Tools
+### Example: Allow Only Specific Tools
 
 ```bash
-npx @confluentinc/mcp-confluent -e .env --allow-tools produce-message,consume-messages
+npx @confluentinc/mcp-confluent -c config.yaml --allow-tools produce-message,consume-messages
 ```
 
 Only the specified tools will be enabled; all others will be disabled.
 
-#### Example: Block Certain Tools
+### Example: Block Certain Tools
 
 ```bash
-npx @confluentinc/mcp-confluent -e .env --block-tools produce-message,consume-messages
+npx @confluentinc/mcp-confluent -c config.yaml --block-tools produce-message,consume-messages
 ```
 
 All tools except the specified ones will be enabled.
 
-#### Example: Use Tool Lists from Files
+### Example: Use Tool Lists from Files
 
 You can also maintain allow/block lists in files (one tool name per line):
 
 ```bash
-npx -y @confluentinc/mcp-confluent -e .env --allow-tools-file allow.txt --block-tools-file block.txt
+npx -y @confluentinc/mcp-confluent -c config.yaml --allow-tools-file allow.txt --block-tools-file block.txt
 ```
 
-#### Example: List All Available Tools
+### Example: List All Available Tools
 
 ```bash
 npx -y @confluentinc/mcp-confluent --list-tools
@@ -337,59 +337,103 @@ npx -y @confluentinc/mcp-confluent --list-tools
 <summary>Show output</summary>
 
 ```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.
-check-flink-statement-health: Perform an aggregate health check for a Flink SQL statement.
-describe-flink-table: Get full schema details for a Flink table via INFORMATION_SCHEMA.COLUMNS.
-detect-flink-statement-issues: Detect issues for a Flink SQL statement by analyzing status, exceptions, and metrics.
-get-flink-statement-profile: Get Query Profiler data with task graph, metrics, and automated issue detection.
-get-flink-table-info: Get table metadata via INFORMATION_SCHEMA.TABLES.
-list-flink-catalogs: List all catalogs in the Flink environment.
-list-flink-databases: List all databases (schemas) in a Flink catalog via INFORMATION_SCHEMA.SCHEMATA.
-list-flink-tables: List all tables in a Flink database.
-get-flink-statement-exceptions: Retrieve the 10 most recent exceptions for a Flink SQL statement.
-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.
+billing:
+  list-billing-costs: Retrieve billing cost data for a Confluent Cloud organization within a specified date range with pagination support
+
+catalog:
+  add-tags-to-topic: Assign existing tags to Kafka topics in Confluent Cloud.
+  create-topic-tags: Create new tag definitions in Confluent Cloud.
+  delete-tag: Delete a tag definition from Confluent Cloud.
+  list-tags: Retrieve all tags with definitions from Confluent Cloud Schema Registry.
+  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.
+
+confluent-cloud:
+  list-clusters: Get all clusters in the Confluent Cloud environment
+  list-environments: Get all environments in Confluent Cloud with pagination support
+  list-organizations: List Confluent Cloud organizations the current credentials can see. Paginated; if the response includes a nextPageTok...
+  read-environment: Get details of a specific environment by ID
+
+connect:
+  create-connector: Create a new connector. Returns the new connector information if successful.
+  delete-connector: Delete an existing connector. Returns success message if deletion was successful.
+  get-connector-config: Retrieve the full configuration map for a connector. Returns the flat config object the connector was created/updated...
+  get-connector-error-recommendations: Get suggested remediation steps for a connector that has failed or is in an error state. Returns a one-liner when no recommendations are available.
+  get-connector-error-summary: Summarize a connector's current errors. Projects Confluent Cloud's /status diagnostics into a compact, agent-friendly form. Returns a one-liner when the connector is healthy.
+  get-connector-logs: Retrieve recent log entries for a Confluent Cloud connector from the Cloud logging API. Defaults to the last hour of ERROR-level entries. Paginated via nextPageToken.
+  get-connector-offsets: Retrieve current offsets for a connector's tasks. Useful for detecting lag, stalled tasks, or assisting recovery.
+  get-connector-status: Get the current state of a connector and its tasks (RUNNING, FAILED, PAUSED, UNASSIGNED) including failure traces if ...
+  get-connector-tasks: List the tasks of a connector along with their configurations.
+  list-connectors: Retrieve a list of "names" of the active connectors. You can then make a read request for a specific connector by name.
+  pause-connector: Pause a running connector and its tasks. Idempotent.
+  restart-connector: Restart a connector and its tasks. Asynchronous; the connector will not transition state synchronously.
+  resume-connector: Resume a paused connector and its tasks. Idempotent.
+  update-connector-config: Update the configuration of an existing connector. Full-replace: omitted keys are removed and the connector is reconf...
+
+docs:
+  get-product-doc-page: Fetch the full markdown content of a Confluent product documentation page. Accepts URLs under https://docs.confluent....
+  search-product-docs: Search Confluent product documentation (docs.confluent.io, developer.confluent.io, support.confluent.io) by keyword.
+
+flink:
+  check-flink-statement-health: Perform an aggregate health check for a Flink SQL statement. Returns status (healthy/warning/critical), current phase...
+  create-flink-statement: Make a request to create a statement.
+  delete-flink-statements: Make a request to delete a statement.
+  describe-flink-table: Get full schema details for a Flink table via INFORMATION_SCHEMA.COLUMNS. Returns column names, data types (including...
+  detect-flink-statement-issues: Detect issues for a Flink SQL statement by analyzing status, exceptions, and performance metrics. Identifies problems...
+  get-flink-statement-exceptions: Retrieve the 10 most recent exceptions for a Flink SQL statement. Useful for diagnosing failed or failing statements.
+  get-flink-statement-profile: Get Query Profiler data for a Flink SQL statement. Returns the task graph with human-readable task/operator names, pe...
+  get-flink-table-info: Get table metadata via INFORMATION_SCHEMA.TABLES. Returns watermark configuration, distribution info, and table type.
+  list-flink-catalogs: List all catalogs available in the Flink environment via INFORMATION_SCHEMA.CATALOGS.
+  list-flink-databases: List all databases (schemas) in a Flink catalog via INFORMATION_SCHEMA.SCHEMATA. Returns catalog and database names.
+  list-flink-statements: Retrieve a sorted, filtered, paginated list of all statements.
+  list-flink-tables: List all tables in a Flink database via INFORMATION_SCHEMA.TABLES. Returns table names and types.
+  read-flink-statement: Make a request to read a statement and its results
+
+kafka:
+  alter-topic-config: Alter topic configuration in Confluent Cloud.
+  consume-messages: Consume messages from Kafka topics. Optionally restrict to a partition, start from an offset, timestamp, earliest, la...
+  create-topics: Create one or more Kafka topics with an optional partition count.
+  delete-topics: Delete the topic with the given names.
+  describe-consumer-group: Describe a single consumer group on a Kafka cluster. Returns the group's state, type, protocol, partition assignor, c...
+  get-consumer-group-lag: Compute live offset lag for a single Kafka consumer group. Returns per-(topic, partition) {committedOffset, highWater...
+  get-partition-offsets: Return per-partition low/high watermarks and message counts for a Kafka topic. Use this to size a backfill, measure l...
+  get-topic-config: Retrieve configuration details for a specific Kafka topic.
+  list-consumer-groups: List consumer groups on a Kafka cluster — wraps the broker's listGroups admin call. Optional filters narrow the resul...
+  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...
+
+mcp-server-diagnostics:
+  explain-disabled-tools: Call when the user asks why a tool is missing or unavailable (e.g., "why can't I list Kafka topics?", "where are the ...
+
+metrics:
+  list-available-metrics: List available Confluent Cloud metrics and their filter fields from the Telemetry API. Use this tool BEFORE query-met...
+  query-metrics: Query Confluent Cloud metrics from the Telemetry API. IMPORTANT: Use the list-available-metrics tool first to discove...
+
+schema-registry:
+  delete-schema: Delete a schema subject or a specific version from the Schema Registry. If version is omitted, all versions of the su...
+  list-schemas: List all schemas in the Schema Registry.
+
+tableflow:
+  create-tableflow-catalog-integration: Make a request to create a catalog integration.
+  create-tableflow-topic: Make a request to create a tableflow topic.
+  delete-tableflow-catalog-integration: Make a request to delete a tableflow catalog integration.
+  delete-tableflow-topic: Make a request to delete a tableflow topic.
+  list-tableflow-catalog-integrations: Retrieve a sorted, filtered, paginated list of all catalog integrations.
+  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-catalog-integration: Make a request to read a catalog integration.
+  read-tableflow-topic: Make a request to read a tableflow topic.
+  update-tableflow-catalog-integration: Make a request to update a catalog integration.
+  update-tableflow-topic: Make a request to update a tableflow topic.
 ```
 
 </details>
 
-> **Tip:** The allow-list is applied before the block-list. If neither is provided, all tools are enabled by default.
+> **Tip:** The allow-list is applied before the block-list.
+> If neither is provided, all tools are enabled by default.
 
-### Configuring MCP Clients
+## Configuring MCP Clients
 
 Please refer to the following guides for step-by-step instructions on setting up and using this MCP server with your preferred client:
 
@@ -398,25 +442,40 @@ Please refer to the following guides for step-by-step instructions on setting up
 - [Cursor](docs/configuring-cursor.md)
 - [Gemini CLI](docs/configuring-gemini-cli.md)
 - [Goose CLI](docs/configuring-goose-cli.md)
+- [IBM Bob](docs/configuring-ibm-bob.md)
 - [VS Code](docs/configuring-vs-code.md)
 - [Windsurf](docs/configuring-windsurf.md)
 
 ## Telemetry
 
-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.
+This MCP server collects usage data to help make improvements.
+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.
 
 ## Troubleshooting
 
-**"Node.js version not supported"** -- This project requires Node.js 22 or later. Check your version with `node -v` and upgrade if needed.
+**"Node.js version not supported"** -- This project requires Node.js 22 or later.
+Check your version with `node -v` and upgrade if needed.
 
-**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.
+**Tools not appearing** -- Each tool requires specific service blocks in your `config.yaml`.
+Run `--list-tools` to see which tools are active, or invoke the `explain-disabled-tools` MCP tool from your client for a per-tool reason.
+The block-to-tool mapping lives in [CONFIGURATION.md](CONFIGURATION.md#tool-enablement-which-block-lights-up-what).
 
-**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).
+**Authentication errors on HTTP/SSE** -- Generate an API key with `npx @confluentinc/mcp-confluent --generate-key` and add it to your `config.yaml` under `server.auth.api_key`.
+See [CONFIGURATION.md → HTTP/SSE transport security](CONFIGURATION.md#httpsse-transport-security).
 
-**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.
+**Connection refused / port conflicts** -- The default HTTP port is 8080.
+Set `server.http.port` in your `config.yaml` to change it.
 
-**Tableflow authorization errors** -- Tableflow tools require specific IAM permissions in your cloud environment. See [Prerequisites & Setup for Tableflow Commands](#prerequisites--setup-for-tableflow-commands).
+**Tableflow authorization errors** -- Tableflow tools require specific IAM permissions in your cloud environment.
+See [Prerequisites & setup for Tableflow commands](#prerequisites--setup-for-tableflow-commands).
 
 ## Contributing
 
-Bug reports and feedback is appreciated in the form of Github Issues. For guidelines on contributing please see [CONTRIBUTING.md](CONTRIBUTING.md)
+Bug reports and feedback is appreciated in the form of Github Issues.
+For guidelines on contributing please see [CONTRIBUTING.md](CONTRIBUTING.md)
+
+### Pre-release testing
+
+To run the MCP server against a pre-release version for beta testing or early feedback, download the release tarball file to a local directory.
+Then, when running any of the `npx` commands above, replace `@confluentinc/mcp-confluent` with the path to that tarball, e.g. `npx @~path/to/my/tarball --list-tools`