Add new MCP rpk docs (#1358)

Author: JakeSCahill

modules/reference/partials/rpk-cloud/rpk-cloud-mcp-install.adoc

@@ -1,11 +1,10 @@
 = rpk cloud mcp install
-// tag::single-source[]
-
-Install Redpanda Cloud MCP server.
+:description: Install the local MCP server for Redpanda Cloud configuration.
 
-Only Claude Desktop is supported at this time.
+// tag::single-source[]
+Install the MCP client configuration to connect your AI assistant to the local MCP server for Redpanda Cloud.
 
-Writes an mcpServer entry with name "redpandaCloud" into `claude_desktop_config.json` in Claude Desktop's config directory.
+This command generates and installs the necessary configuration files for your MCP client (like Claude Code) to automatically connect to the local MCP server for Redpanda Cloud. The local MCP server provides your AI assistant with tools to manage your Redpanda Cloud account and clusters.
 
 == Usage
 
@@ -14,15 +13,24 @@ Writes an mcpServer entry with name "redpandaCloud" into `claude_desktop_config.
 rpk cloud mcp install [flags]
 ----
 
+== Examples
+
+Install configuration for Claude Code:
+
+[,bash]
+----
+rpk cloud mcp install --client claude-code
+----
+
 == Flags
 
 [cols="1m,1a,2a"]
 |===
 |*Value* |*Type* |*Description*
 
-|--allow-delete |- |Allows the deletion of RPCs.
+|--allow-delete |- |Allow delete operations (RPCs). Off by default.
 
-|--client |string |Name of the MCP client to configure (default "claude").
+|--client |string |Name of the MCP client to configure. Supported values: `claude` or `claude-code`.
 
 |-h, --help |- |Help for install.
 
@@ -35,4 +43,9 @@ rpk cloud mcp install [flags]
 |-v, --verbose |- |Enable verbose logging.
 |===
 
+== Suggested reading
+
+* xref:ai-agents:mcp/local/quickstart.adoc[]
+* xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-stdio.adoc[]
+
 // end::single-source[]

modules/reference/partials/rpk-cloud/rpk-cloud-mcp-proxy.adoc

@@ -0,0 +1,80 @@
+= rpk cloud mcp proxy
+:description: Proxy MCP requests to Remote MCP servers in Redpanda Cloud
+
+// tag::single-source[]
+
+*Introduced in version 25.2.3*.
+
+Proxy MCP requests from your local AI client to a remote MCP server running in your Redpanda Cloud cluster.
+
+This command acts as a bridge between your AI assistant (like Claude) and your remote MCP server. It handles connection management, and request proxying so your AI client can use tools hosted in your cluster.
+
+== Modes of operation
+
+*Install mode* (recommended): Generates and installs MCP client configuration files that tell your AI client how to connect. This is a one-time setup operation.
+
+*Proxy mode* (default): Serves stdio and proxies requests in real-time. Your AI client connects to this command's stdio interface, and requests are forwarded to the remote MCP server.
+
+== Usage
+
+[,bash]
+----
+rpk cloud mcp proxy [flags]
+----
+
+== Examples
+
+Proxy requests to a specific MCP server:
+
+[,bash]
+----
+rpk cloud mcp proxy --cluster-id <cluster-id> --mcp-server-id <server-id>
+----
+
+Install Claude Code configuration for connecting to your MCP server in Redpanda Cloud BYOC or Dedicated:
+
+[,bash]
+----
+rpk cloud mcp proxy --install --client claude-code --cluster-id <cluster-id> --mcp-server-id <server-id>
+----
+
+Install Claude Code configuration  for connecting to your MCP server in Redpanda Cloud Serverless:
+
+[,bash]
+----
+rpk cloud mcp proxy --install --client claude-code --serverless-cluster-id <cluster-id> --mcp-server-id <server-id>
+----
+
+== Flags
+
+[cols="1m,1a,2a"]
+|===
+|*Value* |*Type* |*Description*
+
+|--client |string |Name of the MCP client to configure. Required when using `--install`. Supported values: `claude` and `claude-code`.
+
+|--cluster-id |string |Cluster ID where your Remote MCP server is running. Find this in the Redpanda Cloud Console.
+
+|--serverless-cluster-id |string |Serverless cluster ID where your Remote MCP server is running. Find this in the Redpanda Cloud Console.
+
+|-h, --help |- |Help for proxy.
+
+|--install |- |Install MCP client configuration instead of serving stdio. Use this for one-time setup.
+
+|--mcp-server-id |string |ID of the Remote MCP server to connect to. Find this in your cluster's Remote MCP page.
+
+|--config |string |Redpanda or `rpk` config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`.
+
+|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail.
+
+|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details.
+
+|-v, --verbose |- |Enable verbose logging.
+|===
+
+== See also
+
+* xref:ai-agents:mcp/remote/quickstart.adoc[]
+* xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[]
+
+// end::single-source[]

modules/reference/partials/rpk-cloud/rpk-cloud-mcp-stdio.adoc

@@ -1,7 +1,12 @@
 = rpk cloud mcp stdio
+:description: Communicate with local MCP server for Redpanda Cloud using the stdio protocol.
 // tag::single-source[]
 
-MCP `stdio` server. Can be used by MCP clients.
+Communicate with the local MCP server for Redpanda Cloud using the stdio protocol.
+
+This command provides a direct stdio interface for communicating with the local MCP server for Redpanda Cloud. The local MCP server runs on your machine and provides tools for managing your Redpanda Cloud account and clusters. It's typically used as the transport mechanism when your MCP client is configured to use `rpk` as the stdio server process.
+
+Most users should use xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[`rpk cloud mcp install`] instead, which automatically configures your MCP client.
 
 == Usage
 
@@ -10,13 +15,22 @@ MCP `stdio` server. Can be used by MCP clients.
 rpk cloud mcp stdio [flags]
 ----
 
+== Examples
+
+Start the local MCP server for Redpanda Cloud using the stdio protocol:
+
+[,bash]
+----
+rpk cloud mcp stdio
+----
+
 == Flags
 
 [cols="1m,1a,2a"]
 |===
 |*Value* |*Type* |*Description*
 
-|--allow-delete |- |Allows the deletion of RPCs. Off by default.
+|--allow-delete |- |Allow delete operations (RPCs). Off by default.
 
 |-h, --help |- |Help for stdio.
 
@@ -29,4 +43,9 @@ rpk cloud mcp stdio [flags]
 |-v, --verbose |- |Enable verbose logging.
 |===
 
+== Suggested reading
+
+* xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[]
+* xref:ai-agents:mcp/local/overview.adoc[]
+
 // end::single-source[]

modules/reference/partials/rpk-cloud/rpk-cloud-mcp.adoc

@@ -1,13 +1,35 @@
 = rpk cloud mcp
+:description: Manage connections to MCP servers in Redpanda Cloud.
 // tag::single-source[]
 
+Manage connections to MCP servers in Redpanda Cloud. This includes both the local MCP server for Redpanda Cloud and remote MCP servers (managed).
+
+These commands help you connect AI assistants like Claude to different types of MCP servers:
+
+* **Local MCP server for Redpanda Cloud**: Runs on your local machine and provides access to your Redpanda Cloud account and clusters
+* **Remote MCP servers**: Custom servers you build and deploy that run inside your Redpanda Cloud clusters
+
 == Usage
 
 [,bash]
 ----
-rpk cloud mcp [command] [flags]
+rpk cloud mcp [flags]
+  rpk cloud mcp [command]
 ----
 
+== Subcommands
+
+[cols="1m,2a"]
+|===
+|Command |Description
+
+|xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-install.adoc[install] |Install the local MCP server for Redpanda Cloud configuration.
+
+|xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-proxy.adoc[proxy] |Proxy requests to Remote MCP servers.
+
+|xref:reference:rpk/rpk-cloud/rpk-cloud-mcp-stdio.adoc[stdio] |Communicate with the local MCP server for Redpanda Cloud using the stdio protocol.
+|===
+
 == Flags
 
 [cols="1m,1a,2a"]
@@ -25,4 +47,10 @@ rpk cloud mcp [command] [flags]
 |-v, --verbose |- |Enable verbose logging.
 |===
 
+== Suggested reading
+
+* xref:ai-agents:mcp/local/quickstart.adoc[]
+* xref:ai-agents:mcp/remote/quickstart.adoc[]
+* xref:ai-agents:mcp/overview.adoc[]
+
 // end::single-source[]