docs: DOC-1649 Redpanda Cloud MCP Server

local-antora-playbook.yml

@@ -16,6 +16,9 @@ content:
     branches: HEAD
   - url: https://github.com/redpanda-data/documentation
     branches: [main, v/*, shared, site-search]
+  - url: https://github.com/redpanda-data/docs-site
+    branches: [main]
+    start_paths: [home]
   - url: https://github.com/redpanda-data/redpanda-labs
     branches: main
     start_paths: [docs,'*/docs']

modules/ROOT/nav.adoc

@@ -69,9 +69,10 @@
 ** xref:security:secrets.adoc[Secrets]
 ** xref:security:cloud-safety-reliability.adoc[Safety and Reliability]
 
-
-* xref:develop:agents/about.adoc[AI Agents]
-** xref:develop:agents/create-support-agent.adoc[]
+* xref:ai-agents:mcp/local/index.adoc[]
+** xref:ai-agents:mcp/local/overview.adoc[Overview]
+** xref:ai-agents:mcp/local/quickstart.adoc[Quickstart]
+** xref:ai-agents:mcp/local/configuration.adoc[Configure]
 
 * xref:develop:connect/about.adoc[Redpanda Connect]
 ** xref:develop:connect/connect-quickstart.adoc[Quickstart]
@@ -486,6 +487,9 @@
 ***** xref:reference:rpk/rpk-cloud/rpk-cloud-cluster-select.adoc[]
 **** xref:reference:rpk/rpk-cloud/rpk-cloud-login.adoc[]
 **** xref:reference:rpk/rpk-cloud/rpk-cloud-logout.adoc[]
+**** rpk cloud mcp
+***** xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[]
+***** xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-stdio.adoc[]
 *** xref:reference:rpk/rpk-cluster/rpk-cluster.adoc[]
 **** xref:reference:rpk/rpk-cluster/rpk-cluster-config.adoc[]
 ***** xref:reference:rpk/rpk-cluster/rpk-cluster-config-get.adoc[]

modules/ai-agents/pages/mcp/local/configuration.adoc

@@ -0,0 +1,204 @@
+= Configure Redpanda Cloud MCP
+:page-beta: true
+:description: Learn how to configure the Redpanda Cloud MCP Server for your AI assistant, including auto and manual client setup, enabling deletes, and security considerations.
+
+This page explains how to configure the Redpanda Cloud MCP Server for your AI assistant, including auto and manual client setup, enabling deletes, and security considerations.
+
+== Prerequisites
+
+* At least version 25.2.3 of xref:manage:rpk/rpk-install.adoc[`rpk` installed on your computer]
+* Access to a Redpanda Cloud account
+* Supported AI client (Claude, Claude Code, or other MCP-compatible client)
+
+== Endpoint availability
+
+The MCP server exposes Redpanda Cloud API endpoints through `rpk`. Available endpoints depend on your `rpk` version. Newer API features require updated versions of `rpk`.
+
+TIP: Keep `rpk` updated to the latest version to access new Redpanda Cloud features through the MCP server. New MCP endpoints are documented in Redpanda link:https://github.com/redpanda-data/redpanda/releases[release notes].
+
+== Auto-configured clients (Claude and Claude Code)
+
+For some supported clients, you can install and configure the MCP integration using the xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[`rpk cloud mcp install` command].
+For Claude and Claude Code, run one of these commands:
+
+```bash
+# Choose one
+rpk cloud mcp install --client claude
+rpk cloud mcp install --client claude-code
+```
+
+If you need to update the integration, re-run the install command for your client.
+
+== Manual configuration for other MCP clients
+
+If you're using another MCP-compatible client, you can manually configure it to use Redpanda Cloud MCP Server. Follow these steps:
+
+Add an MCP server entry to your client's configuration (example shown in JSON). Adjust paths for your system.
+
+```json
+"mcpServers": {
+  "redpandaCloud": {
+    "command": "rpk",
+    "args": [
+      "--config",
+      "<path-to-rpk.yaml>", <1>
+      "cloud",
+      "mcp",
+      "stdio"
+    ]
+  }
+}
+```
+<1> The `--config` flag lets you target a specific `rpk.yaml`, which contains the configuration for connecting to your cluster. Always use the same config path as you used for `rpk cloud login` to ensure it has your token. Paths vary by OS and install method. See the xref:reference:rpk/rpk-cloud/rpk-cloud-login.adoc[`rpk cloud login`] reference for the default paths.
+
+[TIP]
+====
+You can also <<local, start the server manually in a terminal to observe logs and troubleshoot>>.
+====
+
+== Enable delete operations
+
+Destructive operations are **disabled by default**. To allow delete operations, add `--allow-delete` to the MCP server invocation.
+
+CAUTION: Enabling delete operations permits actions like **deleting topics or clusters**. Restrict access to your AI client and double-check prompts.
+
+[tabs]
+====
+Auto-configured clients::
++
+--
+```bash
+# Choose one
+rpk cloud mcp install --client claude --allow-delete
+rpk cloud mcp install --client claude-code --allow-delete
+```
+--
+Manual configuration example::
++
+--
+```json
+"mcpServers": {
+  "redpandaCloud": {
+    "command": "rpk",
+    "args": [
+      "cloud",
+      "mcp",
+      "stdio",
+      "--allow-delete"
+    ]
+  }
+}
+```
+--
+====
+
+== Configuration locations and paths
+
+Most `rpk` commands accept a `--config` flag, which lets you specify the exact `rpk.yaml` configuration file to use. This flag overrides the default search path and ensures that the command uses the credentials and settings from the file you provide. Using `--config` is the best way to control which Redpanda Cloud account and cluster your commands operate on when working with multiple environments or service accounts.
+
+Always use the same config path for both `rpk cloud login` and any MCP server setup or install commands to avoid authentication issues. By default, `rpk` searches for config files in standard locations depending on your OS and install method—see the xref:reference:rpk/rpk-cloud/rpk-cloud-login.adoc[reference documentation] for details. Use an absolute path and make sure your user has read and write permissions. For best results, keep your config files secure and never share them.
+
+For example, if you want to use a custom config path, specify it for both login and the MCP install command:
+
+[source,bash]
+----
+rpk cloud login --config /Users/<user>/my-rpk-config.yaml
+rpk cloud mcp install --client claude --config /Users/<user>/my-rpk-config.yaml
+----
+
+Or for Claude Code:
+
+[source,bash]
+----
+rpk cloud login --config /Users/<user>/my-rpk-config.yaml
+rpk cloud mcp install --client claude-code --config /Users/<user>/my-rpk-config.yaml
+----
+
+== Update or remove the MCP server
+
+To update, re-run the xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[`rpk cloud mcp install` command].
+To remove, delete or disable the `mcpServers.redpandaCloud` entry in your client's config. (Steps vary by client.)
+
+== Security considerations
+
+* Avoid enabling `--allow-delete` unless required.
+* For most local use cases (such as with Claude or Claude Code), log in with your personal Redpanda Cloud user account for better security and easier management.
+* If you are deploying the MCP server as part of an application or shared environment, consider using a xref:security:cloud-authentication.adoc#authenticate-to-the-cloud-api[service account] with tailored roles. To log in as a service account, use:
++
+[source,bash]
+----
+rpk cloud login --client-id <service-account-client-id> --client-secret <service-account-client-secret> --save
+----
++
+You can also use these additional flags as needed:
++
+** `--no-browser`: Prevents auto-opening the authentication URL.
+** `--no-profile`: Skips automatic profile creation and prompts.
+* Regularly review and rotate your credentials.
+
+== Troubleshooting
+
+=== Quick checks
+
+. Make sure you are using at least version 25.2.3 of `rpk`.
+. If you see authentication errors, run `rpk cloud login` again.
+. Ensure you installed for the right client:
++
+```bash
+rpk cloud mcp install --client claude
+# or
+rpk cloud mcp install --client claude-code
+```
+. If using another MCP client, verify your `mcpServers.redpandaCloud` entry (paths, JSON syntax, and args order).
+
+. [[local]]Start the server manually using the xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-stdio.adoc[`rpk cloud mcp stdio` command] (one-time login required) to verify connectivity to Redpanda Cloud endpoints:
+
++
+[source,bash]
+----
+rpk cloud login
+rpk cloud mcp stdio
+----
++
+.. Send the following newline-delimited JSON-RPC messages (each on its own line):
++
+[source,json]
+----
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"roots":{},"sampling":{},"elicitation":{}},"clientInfo":{"name":"ManualTest","version":"0.1.0"}}}
+{"jsonrpc":"2.0","method":"notifications/initialized"}
+{"jsonrpc":"2.0","id":2,"method":"tools/list"}
+----
++
+Expected response shapes (examples):
++
+[source,json]
+----
+{"jsonrpc":"2.0","id":1,"result":{"capabilities":{...}}}
+{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"...","description":"..."}, ...]}}
+----
++
+.. Stop the server with `Ctrl+C`.
+
+== Common issues
+
+The server runs locally, but it must reach Redpanda Cloud endpoints to perform operations.
+
+=== Client can't find the MCP server
+
+* Re-run the install for your MCP client.
+* Confirm the path in `--config /path/to/rpk.yaml` exists and is readable.
+* Double-check your client's configuration format and syntax.
+
+=== Unauthorized errors or token errors
+
+Your capabilities depend on your Redpanda Cloud account permissions. If an operation fails with a permissions error, contact your account admin.
+
+* Run `rpk cloud login` to refresh the token.
+* Ensure your account has the necessary permissions for the requested operation.
+
+=== Deletes not working
+
+* By default, delete operations are **disabled**. Add `--allow-delete` to the server invocation (auto or manual configuration) and restart the client.
+* For auto-configured clients, you may need to edit the generated config or re-run the install command and adjust the entry.
+
+

modules/ai-agents/pages/mcp/local/index.adoc

@@ -0,0 +1,5 @@
+= Redpanda Cloud MCP Server
+:page-beta: true
+:description: Find links to information about the Redpanda Cloud MCP Server and its features for building and managing AI agents that can interact with your Redpanda Cloud account and clusters.
+:page-layout: index
+:page-aliases: develop:agents/about.adoc

modules/ai-agents/pages/mcp/local/overview.adoc

@@ -0,0 +1,53 @@
+
+= About the Redpanda Cloud MCP Server
+:page-beta: true
+:description: Learn about the Redpanda Cloud MCP Server, which lets AI assistants securely access and operate your Redpanda Cloud account and clusters.
+
+Redpanda Cloud MCP Server lets AI assistants securely access and operate your Redpanda Cloud account and clusters. MCP provides controlled access to:
+
+* **Control plane** actions, such as create a Redpanda Cloud cluster, list clusters.
+* **Data plane** actions, such as list/create topics, read messages from topics.
+
+By speaking natural language to your assistant, you can ask it to perform Redpanda operations on your behalf. The MCP server runs locally on your machine and authenticates to Redpanda Cloud using a Redpanda Cloud token.
+
+image::shared:cloud-mcp.gif[A terminal window showing Claude Code invoking Redpanda Cloud MCP to list topics in a cluster.]
+
+== What you can do
+
+Typical requests you can make to your assistant once connected:
+
+* Create a Redpanda Cloud cluster named `dev-mcp`.
+* List topics in `dev-mcp`.
+* Create a topic `orders-raw` with 6 partitions.
+* Read the last 20 messages from `orders-raw`.
+
+NOTE: The MCP server does **not** expose delete endpoints by default. You can enable delete endpoints when you create the server if you intentionally want to allow delete operations.
+
+== Use cases
+
+* Test automation: Create short-lived clusters, seed topics, and validate pipelines quickly.
+* Operational assistance: Inspect health, list topics, or tail messages during incidents.
+* Data exploration: Read samples to validate schemas and transformations.
+* Onboarding and demos: Let team members issue high-level requests without memorizing every CLI flag.
+
+== How it works
+
+. *Authentication:* Authenticate to Redpanda Cloud and receive a token using the xref:reference:rpk/rpk-cloud/rpk-cloud-login.adoc[`rpk cloud login` command].
+. *Local MCP server:*: Configure your client using the xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[`rpk cloud mcp install`] command. Your client then starts the server on-demand using xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-stdio.adoc[`rpk cloud mcp stdio`], authenticating with the Redpanda Cloud token from `rpk cloud login`.
+
+. *Prompting:* After connecting, you can prompt your assistant to perform Redpanda operations, and the local MCP server executes them in your Redpanda Cloud account using your credentials.
+
+=== Components
+
+* AI client (Claude, Claude Code, or any other MCP client)
+* Redpanda CLI (`rpk`)
+* Redpanda Cloud (control plane and data plane)
+
+== Next steps
+
+* xref:ai-agents:mcp/local/quickstart.adoc[]
+* xref:ai-agents:mcp/local/configuration.adoc[]
+
+== Suggested reading
+
+The Redpanda documentation site has a read-only MCP server that provides access to Redpanda docs and examples. This server has no access to your Redpanda Cloud account or clusters. See xref:home:ROOT:mcp-setup.adoc[].

modules/ai-agents/pages/mcp/local/quickstart.adoc

@@ -0,0 +1,68 @@
+= Redpanda Cloud MCP Quickstart
+:page-beta: true
+:description: Connect your Claude AI assistant to your Redpanda Cloud account and clusters using the Redpanda Cloud MCP Server.
+
+In this quickstart, you'll get your Claude AI assistant talking to Redpanda Cloud using the xref:ai-agents:mcp/local/overview.adoc[Redpanda Cloud MCP Server].
+
+////
+To be used when Remote MCP is ready for public beta
+
+If you're trying to deploy your own MCP server as a managed service inside your cluster, see xref:ai-agents:mcp/remote/quickstart.adoc[].
+////
+
+== Prerequisites
+
+* At least version 25.2.3 of xref:manage:rpk/rpk-install.adoc[`rpk` installed on your computer]
+* Access to a Redpanda Cloud account
+* link:https://support.anthropic.com/en/articles/10065433-installing-claude-desktop[Claude] or link:https://docs.anthropic.com/en/docs/claude-code/setup[Claude Code] installed
++
+TIP: For other clients, see xref:ai-agents:mcp/local/configuration.adoc[].
+
+== Set up the MCP server
+
+. Verify your `rpk` version
++
+```bash
+rpk version
+```
++
+Ensure the version is 25.2.3+.
+
+. Log in to Redpanda Cloud
++
+```bash
+rpk cloud login
+```
++
+A browser window opens. Sign in to grant access. After you sign in, `rpk` stores a token locally. This token is not shared with your AI assistant. It is used by the MCP server to authenticate requests to your Redpanda Cloud account.
+
+. Install the MCP integration. Choose one client:
++
+```bash
+# Claude desktop
+rpk cloud mcp install --client claude
+
+# Claude Code (IDE)
+rpk cloud mcp install --client claude-code
+```
++
+This command configures the MCP server for your client. If you need to update the integration, re-run the install command for your client.
+
+== Start prompting
+
+Launch Claude or Claude Code and try one of these prompts:
+
+* “Create a Redpanda Cloud cluster named `dev-mcp`.”
+* “List topics in `dev-mcp`.”
+* “Create a topic `orders-raw` with 6 partitions.”
+* “Read the last 20 messages from `orders-raw`.”
+
+:note-caption: Delete operations are opt-in
+
+NOTE: The MCP server does *not* expose API endpoints that result in delete operations by default. Use `--allow-delete` only if you intentionally want to enable delete operations. See xref:ai-agents:mcp/local/configuration.adoc#_enable_delete_operations[Enable delete operations].
+
+:note-caption: Note
+
+== Next steps
+
+* xref:ai-agents:mcp/local/configuration.adoc[]