|
| 1 | += Configure Redpanda Cloud MCP |
| 2 | +:page-beta: true |
| 3 | +: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. |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +== Prerequisites |
| 8 | + |
| 9 | +* At least version 25.2.3 of xref:manage:rpk/rpk-install.adoc[`rpk` installed on your computer] |
| 10 | +* Access to a Redpanda Cloud account |
| 11 | +* Supported AI client (Claude, Claude Code, or other MCP-compatible client) |
| 12 | + |
| 13 | +== Endpoint availability |
| 14 | + |
| 15 | +The MCP server exposes Redpanda Cloud API endpoints for both the link:https://docs.redpanda.com/api/doc/cloud-controlplane/[Control Plane] and the link:https://docs.redpanda.com/api/doc/cloud-dataplane/[Data Plane] through `rpk`. Available endpoints depend on your `rpk` version. Newer API features require updated versions of `rpk`. |
| 16 | + |
| 17 | +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]. |
| 18 | + |
| 19 | +== Auto-configured clients (Claude and Claude Code) |
| 20 | + |
| 21 | +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]. |
| 22 | +For Claude and Claude Code, run one of these commands: |
| 23 | + |
| 24 | +```bash |
| 25 | +# Choose one |
| 26 | +rpk cloud mcp install --client claude |
| 27 | +rpk cloud mcp install --client claude-code |
| 28 | +``` |
| 29 | + |
| 30 | +If you need to update the integration, re-run the install command for your client. |
| 31 | + |
| 32 | +== Manual configuration for other MCP clients |
| 33 | + |
| 34 | +If you're using another MCP-compatible client, you can manually configure it to use Redpanda Cloud MCP Server. Follow these steps: |
| 35 | + |
| 36 | +Add an MCP server entry to your client's configuration (example shown in JSON). Adjust paths for your system. |
| 37 | + |
| 38 | +```json |
| 39 | +"mcpServers": { |
| 40 | + "redpandaCloud": { |
| 41 | + "command": "rpk", |
| 42 | + "args": [ |
| 43 | + "--config", |
| 44 | + "<path-to-rpk.yaml>", <1> |
| 45 | + "cloud", |
| 46 | + "mcp", |
| 47 | + "stdio" |
| 48 | + ] |
| 49 | + } |
| 50 | +} |
| 51 | +``` |
| 52 | +<1> Optional: The `--config` flag lets you target a specific `rpk.yaml`, which contains the configuration for connecting to your cluster. Always use the same configuration path as you used for `rpk cloud login` to ensure it has your token. Default paths vary by operating system. See the xref:reference:rpk/rpk-cloud/rpk-cloud-login.adoc[`rpk cloud login`] reference for the default paths. |
| 53 | + |
| 54 | +[TIP] |
| 55 | +==== |
| 56 | +You can also <<local, start the server manually in a terminal to observe logs and troubleshoot>>. |
| 57 | +==== |
| 58 | + |
| 59 | +== Enable delete operations |
| 60 | + |
| 61 | +Destructive operations are **disabled by default**. To allow delete operations, add `--allow-delete` to the MCP server invocation. |
| 62 | + |
| 63 | +CAUTION: Enabling delete operations permits actions like **deleting topics or clusters**. Restrict access to your AI client and double-check prompts. |
| 64 | + |
| 65 | +[tabs] |
| 66 | +==== |
| 67 | +Auto-configured clients:: |
| 68 | ++ |
| 69 | +-- |
| 70 | +```bash |
| 71 | +# Choose one |
| 72 | +rpk cloud mcp install --client claude --allow-delete |
| 73 | +rpk cloud mcp install --client claude-code --allow-delete |
| 74 | +``` |
| 75 | +-- |
| 76 | +Manual configuration example:: |
| 77 | ++ |
| 78 | +-- |
| 79 | +```json |
| 80 | +"mcpServers": { |
| 81 | + "redpandaCloud": { |
| 82 | + "command": "rpk", |
| 83 | + "args": [ |
| 84 | + "cloud", |
| 85 | + "mcp", |
| 86 | + "stdio", |
| 87 | + "--allow-delete" |
| 88 | + ] |
| 89 | + } |
| 90 | +} |
| 91 | +``` |
| 92 | +-- |
| 93 | +==== |
| 94 | + |
| 95 | +== Configuration locations and paths |
| 96 | + |
| 97 | +All `rpk` commands accept a `--config` flag, which lets you specify the exact `rpk.yaml` configuration file to use for connecting to your Redpanda cluster. This flag overrides the default search path and ensures that the command uses the credentials and settings from the file you provide. |
| 98 | + |
| 99 | +Always use the same configuration 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 operating system. 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. |
| 100 | + |
| 101 | +CAUTION: The `rpk` configuration file contains your Redpanda Cloud token. Keep the file secure and never share it. |
| 102 | + |
| 103 | +For example, if you want to use a custom config path, specify it for both login and the MCP install command: |
| 104 | + |
| 105 | +[source,bash] |
| 106 | +---- |
| 107 | +rpk cloud login --config /Users/<user>/my-rpk-config.yaml |
| 108 | +rpk cloud mcp install --client claude --config /Users/<user>/my-rpk-config.yaml |
| 109 | +---- |
| 110 | + |
| 111 | +Or for Claude Code: |
| 112 | + |
| 113 | +[source,bash] |
| 114 | +---- |
| 115 | +rpk cloud login --config /Users/<user>/my-rpk-config.yaml |
| 116 | +rpk cloud mcp install --client claude-code --config /Users/<user>/my-rpk-config.yaml |
| 117 | +---- |
| 118 | + |
| 119 | +== Remove the MCP server |
| 120 | + |
| 121 | +To remove the MCP server, delete or disable the `mcpServers.redpandaCloud` entry in your client's config (steps vary by client). |
| 122 | + |
| 123 | +== Security considerations |
| 124 | + |
| 125 | +* Avoid enabling `--allow-delete` unless required. |
| 126 | +* 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. |
| 127 | +* 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: |
| 128 | ++ |
| 129 | +[source,bash] |
| 130 | +---- |
| 131 | +rpk cloud login --client-id <service-account-client-id> --client-secret <service-account-client-secret> --save |
| 132 | +---- |
| 133 | +* Regularly review and rotate your credentials. |
| 134 | + |
| 135 | +== Troubleshooting |
| 136 | + |
| 137 | +=== Quick checks |
| 138 | + |
| 139 | +. Make sure you are using at least version 25.2.3 of `rpk`. |
| 140 | +. If you see authentication errors, run `rpk cloud login` again. |
| 141 | +. Ensure you installed for the right client: |
| 142 | ++ |
| 143 | +```bash |
| 144 | +rpk cloud mcp install --client claude |
| 145 | +# or |
| 146 | +rpk cloud mcp install --client claude-code |
| 147 | +``` |
| 148 | +. If using another MCP client, verify your `mcpServers.redpandaCloud` entry (paths, JSON syntax, and args order). |
| 149 | + |
| 150 | +. [[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: |
| 151 | + |
| 152 | ++ |
| 153 | +[source,bash] |
| 154 | +---- |
| 155 | +rpk cloud login |
| 156 | +rpk cloud mcp stdio |
| 157 | +---- |
| 158 | ++ |
| 159 | +.. Send the following newline-delimited JSON-RPC messages (each on its own line): |
| 160 | ++ |
| 161 | +[source,json] |
| 162 | +---- |
| 163 | +{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"roots":{},"sampling":{},"elicitation":{}},"clientInfo":{"name":"ManualTest","version":"0.1.0"}}} |
| 164 | +{"jsonrpc":"2.0","method":"notifications/initialized"} |
| 165 | +{"jsonrpc":"2.0","id":2,"method":"tools/list"} |
| 166 | +---- |
| 167 | ++ |
| 168 | +Expected response shapes (examples): |
| 169 | ++ |
| 170 | +[source,json] |
| 171 | +---- |
| 172 | +{"jsonrpc":"2.0","id":1,"result":{"capabilities":{...}}} |
| 173 | +{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"...","description":"..."}, ...]}} |
| 174 | +---- |
| 175 | ++ |
| 176 | +.. Stop the server with `Ctrl+C`. |
| 177 | + |
| 178 | +== Common issues |
| 179 | + |
| 180 | +The server runs locally, but it must reach Redpanda Cloud endpoints to perform operations. |
| 181 | + |
| 182 | +=== Client can't find the MCP server |
| 183 | + |
| 184 | +* Re-run the install for your MCP client. |
| 185 | +* Confirm the path in `--config /path/to/rpk.yaml` exists and is readable. |
| 186 | +* Double-check your client's configuration format and syntax. |
| 187 | + |
| 188 | +=== Unauthorized errors or token errors |
| 189 | + |
| 190 | +Your capabilities depend on your Redpanda Cloud account permissions. If an operation fails with a permissions error, contact your account admin. |
| 191 | + |
| 192 | +* Run `rpk cloud login` to refresh the token. |
| 193 | +* Ensure your account has the necessary permissions for the requested operation. |
| 194 | + |
| 195 | +=== Deletes not working |
| 196 | + |
| 197 | +* By default, delete operations are **disabled**. Add `--allow-delete` to the server invocation (auto or manual configuration) and restart the client. |
| 198 | +* For auto-configured clients, you may need to edit the generated config or re-run the install command and adjust the entry. |
| 199 | + |
| 200 | + |
0 commit comments