Improve MCP documentation compliance with Redpanda docs standards (#486)

* Update nav entry for MCP Server for the Redpanda Cloud API

* Improve MCP documentation compliance with style standards

- Add missing learning objectives displays to local overview, quickstart, and configuration pages
- Add intro text following "After [prerequisite], [action]" pattern
- Remove periods from prerequisite fragments per style guide
- Fix passive voice in remote admin pages (admin-guide, manage-servers, monitor-activity, scale-resources)
- Remove redundant Data Plane API section from admin-guide (content belongs in child pages)
- Convert loose paragraph to TIP in configuration page

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* Update local-antora-playbook.yml

* Update index.adoc

* Rename "MCP Server for the Redpanda Cloud API" to "Redpanda Cloud API MCP"

Updated terminology throughout documentation for consistency and brevity.

Changes:
- Navigation entries
- Page titles and descriptions
- Content references
- Cross-reference link text

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* Redpanda Cloud Management MCP Server

* Fix MCP overview title and learning objectives

- Update title to "MCP Servers for Redpanda Cloud Overview"
- Update learning objective 2 to explicitly distinguish between
  "Redpanda Cloud Management MCP Server" and "Remote MCP"

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* Update terminology to Redpanda Cloud Management MCP Server in release notes

- Replace "Redpanda Cloud MCP Server" with "Redpanda Cloud Management MCP Server"
- Change "This local server" to "This server runs on your computer" for clarity

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* Address PR review feedback

Based on feedback from PR #486:

local/overview.adoc:
- Shorten introduction and move learning objectives before image
- Add intro sentence to Components section
- Convert "Suggested reading" section to TIP
- Remove "Continue your learning journey" intro text from Next steps

local/quickstart.adoc:
- Remove "Continue your learning journey" intro text from Next steps

local/configuration.adoc:
- Simplify terminology: "supports the Model Context Protocol" → "supports MCP"

remote/overview.adoc:
- Remove "Continue your learning journey" intro text from Next steps

remote/concepts.adoc:
- Remove "Continue your learning journey" intro text from Next steps

remote/monitor-activity.adoc:
- Fix broken Data Plane API link

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: JakeSCahill

local-antora-playbook.yml

@@ -38,6 +38,7 @@ asciidoc:
   - '@redpanda-data/docs-extensions-and-macros/macros/rp-connect-components'
   - '@redpanda-data/docs-extensions-and-macros/macros/glossary'
   - '@redpanda-data/docs-extensions-and-macros/macros/config-ref'
+  - '@redpanda-data/docs-extensions-and-macros/macros/badge'
   - '@redpanda-data/docs-extensions-and-macros/macros/helm-ref'
   - '@redpanda-data/docs-extensions-and-macros/asciidoc-extensions/add-line-numbers-highlights'
 antora:

modules/ROOT/nav.adoc

@@ -71,7 +71,7 @@
 
 * xref:ai-agents:index.adoc[AI Agents]
 ** xref:ai-agents:mcp/overview.adoc[MCP Overview]
-** xref:ai-agents:mcp/local/index.adoc[Local Redpanda Cloud MCP]
+** xref:ai-agents:mcp/local/index.adoc[Redpanda Cloud Management MCP Server]
 *** xref:ai-agents:mcp/local/overview.adoc[Overview]
 *** xref:ai-agents:mcp/local/quickstart.adoc[Quickstart]
 *** xref:ai-agents:mcp/local/configuration.adoc[Configure]

modules/ai-agents/pages/index.adoc

@@ -5,10 +5,4 @@
 
 AI agents are configurable assistants that autonomously perform specialist tasks by leveraging large language models (LLMs) and connecting to external data sources and tools.
 
-Redpanda Cloud provides two complementary Model Context Protocol (MCP) options to help you build AI agents:
-
-MCP server for the Redpanda Cloud API badge::[label=beta, tooltip={page-beta-text}]::
-A built-in server that gives your AI agent direct access to your Redpanda Cloud account and clusters. This runs locally on your computer and lets you quickly perform operations like creating clusters, listing topics, and reading messages.
-
-Remote MCP::
-Your own custom MCP servers built with Redpanda Connect pipelines and hosted inside your Redpanda Cloud cluster. These let you create reusable tools for your team that integrate with knowledge bases, APIs, and web content while running close to your data.
+Redpanda Cloud provides two complementary Model Context Protocol (MCP) options to help you build AI agents.

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

@@ -1,48 +1,52 @@
-= Configure the MCP Server for the Redpanda Cloud API
+= Configure the Redpanda Cloud Management MCP Server
 :page-beta: true
-:description: Learn how to configure the MCP server for the Redpanda Cloud API, including auto and manual client setup, enabling deletes, and security considerations.
+:description: Learn how to configure the Redpanda Cloud Management MCP Server, including auto and manual client setup, enabling deletes, and security considerations.
 :page-topic-type: how-to
 :personas: ai_agent_developer, platform_admin
 // Reader journey: "I customize and configure"
 // Learning objectives - what readers can learn from this page:
-:learning-objective-1: Configure MCP clients manually
+:learning-objective-1: Configure MCP clients
 :learning-objective-2: Enable delete operations safely
 :learning-objective-3: Troubleshoot common configuration issues
 
-This page explains how to configure the MCP server for the Redpanda Cloud API, including auto and manual client setup, enabling deletes, and security considerations.
+After installing the Redpanda Cloud Management MCP Server, you can configure it for different AI clients, customize security settings, and troubleshoot common issues.
 
-== Prerequisites
+After reading this page, you will be able to:
 
-* 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).
+* [ ] {learning-objective-1}
+* [ ] {learning-objective-2}
+* [ ] {learning-objective-3}
 
-== Endpoint availability
+== Prerequisites
 
-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`.
+* At least version 25.2.3 of xref:manage:rpk/rpk-install.adoc[`rpk` installed on your local machine]
+* Access to a Redpanda Cloud account
+* An MCP-compatible AI client such as Claude, Claude Code, or another tool that supports MCP
 
-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].
+TIP: 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]. Available endpoints depend on your `rpk` version. Keep `rpk` updated 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)
+== Install the integration for Claude or 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
+[source,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
+== Configure other MCP clients manually
 
-If you're using another MCP-compatible client, you can manually configure it to use the MCP server for the Redpanda Cloud API. Follow these steps:
+If you're using another MCP-compatible client, manually configure it to use the Redpanda Cloud Management 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
+[,json]
+----
 "mcpServers": {
   "redpandaCloud": {
     "command": "rpk",
@@ -55,17 +59,15 @@ Add an MCP server entry to your client's configuration (example shown in JSON).
     ]
   }
 }
-```
+----
 <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.
 
-[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.
+The server disables destructive operations 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.
 
@@ -74,16 +76,18 @@ CAUTION: Enabling delete operations permits actions like **deleting topics or cl
 Auto-configured clients::
 +
 --
-```bash
+[,bash]
+----
 # Choose one
 rpk cloud mcp install --client claude --allow-delete
 rpk cloud mcp install --client claude-code --allow-delete
-```
+----
 --
 Manual configuration example::
 +
 --
-```json
+[,json]
+----
 "mcpServers": {
   "redpandaCloud": {
     "command": "rpk",
@@ -95,11 +99,11 @@ Manual configuration example::
     ]
   }
 }
-```
+----
 --
 ====
 
-== Configuration locations and paths
+== Specify configuration file paths
 
 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.
 
@@ -141,23 +145,26 @@ rpk cloud login --client-id <service-account-client-id> --client-secret <service
 
 == Troubleshooting
 
-=== Quick checks
+
+=== Verify your installation
 
 . 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
+[source,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:
++
+[[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]
+[,bash]
 ----
 rpk cloud login
 rpk cloud mcp stdio
@@ -197,7 +204,7 @@ Your capabilities depend on your Redpanda Cloud account permissions. If an opera
 
 === Deletes not working
 
-* By default, delete operations are **disabled**. Add `--allow-delete` to the server invocation (auto or manual configuration) and restart the client.
+* The server disables delete operations by default. 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

@@ -1,4 +1,4 @@
-= MCP Server for the Redpanda Cloud API
+= Redpanda Cloud Management MCP Server
 :page-beta: true
-:description: Find links to information about the MCP server for the Redpanda Cloud API and its features for building and managing AI agents that can interact with your Redpanda Cloud account and clusters.
+:description: Find links to information about the Redpanda Cloud Management MCP Server and its features for building and managing AI agents that can interact with your Redpanda Cloud account and clusters.
 :page-layout: index

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

@@ -1,25 +1,33 @@
-= MCP Server for the Redpanda Cloud API
+= Redpanda Cloud Management MCP Server
 :page-beta: true
-:description: Learn about the MCP server for the Redpanda Cloud API, which lets AI agents securely access and operate your Redpanda Cloud account and clusters.
+:description: Learn about the Redpanda Cloud Management MCP Server, which lets AI agents securely access and operate your Redpanda Cloud account and clusters.
 :page-topic-type: overview
 :personas: evaluator, ai_agent_developer, platform_admin
 // Reader journey: "I'm new"
 // Learning objectives - what readers should understand after reading this page:
-:learning-objective-1: Explain what the MCP server for the Redpanda Cloud API does
+:learning-objective-1: Explain what the Redpanda Cloud Management MCP Server does
 :learning-objective-2: Identify what operations are available through MCP
 :learning-objective-3: Identify security considerations for MCP authentication
 
-The MCP server for the Redpanda Cloud API lets AI agents securely access and operate your Redpanda Cloud account and clusters. MCP provides controlled access to:
+The Redpanda Cloud Management MCP Server lets AI agents securely access and operate your Redpanda Cloud account and clusters through natural language commands.
 
-* link:https://docs.redpanda.com/api/doc/cloud-controlplane/[Control Plane] APIs, such as creating a Redpanda Cloud cluster or listing clusters.
-* link:https://docs.redpanda.com/api/doc/cloud-dataplane/[Data Plane] APIs, such as creating topics or listing topics.
+After reading this page, you will be able to:
 
-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.
+* [ ] {learning-objective-1}
+* [ ] {learning-objective-2}
+* [ ] {learning-objective-3}
 
-image::shared:cloud-mcp.gif[A terminal window showing Claude Code invoking the MCP server for the Redpanda Cloud API to list topics in a cluster.]
+image::shared:cloud-mcp.gif[A terminal window showing Claude Code invoking the Redpanda Cloud Management MCP Server to list topics in a cluster.]
 
 == What you can do
 
+MCP provides controlled access to:
+
+* link:https://docs.redpanda.com/api/doc/cloud-controlplane/[Control Plane] APIs, such as creating a Redpanda Cloud cluster or listing clusters.
+* link:https://docs.redpanda.com/api/doc/cloud-dataplane/[Data Plane] APIs, such as creating topics or listing topics.
+
+The MCP server runs on your computer and authenticates to Redpanda Cloud using a Redpanda Cloud token.
+
 You can do anything that's available in the Control Plane or Data Plane APIs. Typical requests you can make to your assistant once connected include:
 
 * Create a Redpanda Cloud cluster named `dev-mcp`.
@@ -42,6 +50,8 @@ NOTE: The MCP server does **not** expose delete endpoints by default. You can en
 
 === Components
 
+The Redpanda Cloud Management MCP Server requires these components:
+
 * AI client (Claude, Claude Code, or any other MCP client) that connects to the MCP server.
 * Redpanda CLI (`rpk`) for obtaining a token and starting the MCP server.
 * Redpanda Cloud account that the MCP server can connect to and issue API requests.
@@ -56,13 +66,7 @@ MCP servers authenticate to Redpanda Cloud using your personal or service accoun
 
 == Next steps
 
-Continue your learning journey with these resources:
-
-* xref:ai-agents:mcp/local/quickstart.adoc[MCP server for the Redpanda Cloud API quickstart]
-* xref:ai-agents:mcp/local/configuration.adoc[Configure the MCP server for the Redpanda Cloud API]
-
-== Suggested reading
-
-For more information, see these resources:
+* xref:ai-agents:mcp/local/quickstart.adoc[Redpanda Cloud Management MCP Server quickstart]
+* xref:ai-agents:mcp/local/configuration.adoc[Configure the Redpanda Cloud Management MCP Server]
 
-* xref:home:ROOT:mcp-setup.adoc[Read-only MCP server for Redpanda docs]: Access Redpanda documentation and examples through AI agents
+TIP: 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

@@ -1,6 +1,6 @@
-= MCP Server for the Redpanda Cloud API Quickstart
+= Redpanda Cloud Management MCP Server Quickstart
 :page-beta: true
-:description: Connect your Claude AI agent to your Redpanda Cloud account and clusters using the MCP server for the Redpanda Cloud API.
+:description: Connect your Claude AI agent to your Redpanda Cloud account and clusters using the Redpanda Cloud Management MCP Server.
 :page-topic-type: tutorial
 :personas: ai_agent_developer, platform_admin
 // Reader journey: "I'm new" → first hands-on experience
@@ -9,15 +9,21 @@
 :learning-objective-2: Install the MCP integration for Claude
 :learning-objective-3: Issue natural language commands to manage clusters
 
-In this quickstart, you'll get your Claude AI agent talking to Redpanda Cloud using the xref:ai-agents:mcp/local/overview.adoc[MCP server for the Redpanda Cloud API].
+In this quickstart, you'll get your Claude AI agent talking to Redpanda Cloud using the xref:ai-agents:mcp/local/overview.adoc[Redpanda Cloud Management MCP Server].
 
 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[].
 
+After completing this quickstart, you will be able to:
+
+* [ ] {learning-objective-1}
+* [ ] {learning-objective-2}
+* [ ] {learning-objective-3}
+
 == 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.
+* 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[].
 
@@ -67,6 +73,4 @@ NOTE: The MCP server does *not* expose API endpoints that result in delete opera
 
 == Next steps
 
-Continue your learning journey with this resource:
-
-* xref:ai-agents:mcp/local/configuration.adoc[]: Configure the MCP server for advanced use cases
+* xref:ai-agents:mcp/local/configuration.adoc[]

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

@@ -1,11 +1,11 @@
-= MCP Overview
-:description: Learn about Model Context Protocol (MCP) in Redpanda Cloud, including the two complementary options: the MCP server for the Redpanda Cloud API and Remote MCP.
+= MCP Servers for Redpanda Cloud Overview
+:description: Learn about Model Context Protocol (MCP) in Redpanda Cloud, including the two complementary options: the Redpanda Cloud Management MCP Server and Remote MCP.
 :page-topic-type: overview
 :personas: evaluator, ai_agent_developer
 // Reader journey: "I'm new" - understanding the landscape
 // Learning objectives - what readers should understand after reading this page:
 :learning-objective-1: Describe what MCP enables for AI agents
-:learning-objective-2: Distinguish between local and remote MCP options
+:learning-objective-2: Distinguish between Redpanda Cloud Management MCP Server and Remote MCP
 :learning-objective-3: Choose the right MCP option for your use case
 
 This page introduces MCP in Redpanda Cloud and helps you choose the right option for your use case.
@@ -26,7 +26,7 @@ Without MCP, connecting AI to your business systems requires custom API code, au
 
 Redpanda Cloud offers two complementary MCP options:
 
-MCP server for the Redpanda Cloud API badge::[label=beta, tooltip={page-beta-text}]::
+Redpanda Cloud Management MCP Server badge::[label=beta, tooltip={page-beta-text}]::
 A pre-built server that gives AI agents access to Redpanda Cloud APIs. It runs on your computer and lets you manage clusters, topics, and other resources through natural language.
 +
 Example: "Create a cluster called `dev-analytics` with 3 brokers."
@@ -40,7 +40,7 @@ Example: "Analyze the last 100 orders and show me the top product categories."
 
 [cols="1h,2,2"]
 |===
-| | MCP server for the Redpanda Cloud API | Remote MCP
+| | Redpanda Cloud Management MCP Server | Remote MCP
 
 | Purpose
 | Operate your Redpanda Cloud account
@@ -67,7 +67,7 @@ Example: "Analyze the last 100 orders and show me the top product categories."
 
 Choose based on what you want to accomplish:
 
-**Use the MCP server for the Redpanda Cloud API** when you want to:
+**Use the Redpanda Cloud Management MCP Server** when you want to:
 
 * Manage Redpanda Cloud resources without memorizing CLI commands
 * Quickly create test clusters, topics, or users
@@ -81,7 +81,7 @@ Choose based on what you want to accomplish:
 * Connect AI agents to external systems (databases, APIs, LLMs)
 * Run tools close to your data with managed infrastructure
 
-You can use both options together. For example, use the MCP server for the Redpanda Cloud API to create a cluster, then deploy Remote MCP tools to analyze data in that cluster.
+You can use both options together. For example, use the Redpanda Cloud Management MCP Server to create a cluster, then deploy Remote MCP tools to analyze data in that cluster.
 
 == Get started