Merge pull request #4 from redpanda-data/adp-mcp-servers-rewrite

docs(mcp-servers): rewrite MCP Servers pages for ADP GA

Author: micheleRP

local-antora-playbook.yml

@@ -11,13 +11,13 @@ urls:
 output:
   clean: true
 content:
-  sources:
-  - url: https://github.com/redpanda-data/adp-docs
-    branches: main
+  sources: 
+  - url: .
+    branches: HEAD
   - url: https://github.com/redpanda-data/docs
-    branches: [main, v/*, api, shared, site-search,'!v-end-of-life/*']
+    branches: [main, v/*, shared, site-search,'!v-end-of-life/*']
   - url: https://github.com/redpanda-data/cloud-docs
-    branches: feature/remove-ai-agents
+    branches: main
   - url: https://github.com/redpanda-data/redpanda-labs
     branches: main
     start_paths: [docs,'*/docs']

modules/ROOT/nav.adoc

@@ -23,24 +23,21 @@
 **** xref:agents:tutorials/customer-support-agent.adoc[Customer support agent]
 **** xref:agents:tutorials/transaction-dispute-resolution.adoc[Transaction dispute resolution]
 * MCP Servers
-** xref:mcp:overview.adoc[Overview]
-*** Remote MCP
-**** xref:mcp:remote/overview.adoc[Overview]
-**** xref:mcp:remote/quickstart.adoc[Quickstart]
-**** xref:mcp:remote/concepts.adoc[Concepts]
-**** xref:mcp:remote/create-tool.adoc[Create tools]
-**** xref:mcp:remote/register-external.adoc[Register a self-hosted server]
-**** xref:mcp:remote/oauth-user-delegated.adoc[User-delegated OAuth]
-**** xref:mcp:remote/patterns.adoc[Patterns]
-**** xref:mcp:remote/best-practices.adoc[Best practices]
-**** xref:mcp:remote/manage-servers.adoc[Manage servers]
-**** xref:mcp:remote/monitor-mcp-servers.adoc[Monitor servers]
-**** xref:mcp:remote/scale.adoc[Scaling]
-**** xref:mcp:remote/troubleshooting.adoc[Troubleshooting]
-*** Local MCP
-**** xref:mcp:local/overview.adoc[Overview]
-**** xref:mcp:local/quickstart.adoc[Quickstart]
-**** xref:mcp:local/configuration.adoc[Configuration]
+** xref:mcp:index.adoc[Overview]
+** xref:mcp:create-server.adoc[Create a server]
+** xref:mcp:register-remote.adoc[Register a self-managed server]
+** xref:mcp:user-delegated-oauth.adoc[User-delegated OAuth]
+** xref:mcp:test-tools.adoc[Test a server's tools]
+** xref:mcp:managed-catalog.adoc[Managed catalog]
+*** xref:mcp:managed/sql.adoc[SQL]
+*** xref:mcp:managed/kafka.adoc[Kafka]
+*** xref:mcp:managed/slack.adoc[Slack]
+*** xref:mcp:managed/jira.adoc[Jira]
+*** xref:mcp:managed/openapi.adoc[OpenAPI]
+* Redpanda Cloud Management MCP Server
+** xref:mcp:local/index.adoc[Overview]
+** xref:mcp:local/quickstart.adoc[Quickstart]
+** xref:mcp:local/configuration.adoc[Configuration]
 * AI Gateway
 ** xref:ai-gateway:overview.adoc[Overview]
 ** xref:ai-gateway:gateway-quickstart.adoc[Quickstart]

modules/ROOT/pages/adp-overview.adoc

@@ -1,6 +1,6 @@
 = Redpanda Agentic Data Plane Overview
 :description: Enterprise-grade infrastructure for building, deploying, and governing AI agents at scale with compliance-grade audit trails.
-:page-aliases: redpanda-cloud:ai-agents:adp-overview.adoc
+// TODO: Add 'redpanda-cloud:ai-agents:adp-overview.adoc' to page-aliases after ai-agents is removed from cloud-docs
 :page-topic-type: overview
 :page-categories: Agentic Data Plane
 :personas: evaluator, ai_agent_developer, platform_admin
@@ -40,7 +40,7 @@ Under the hood, MCP servers wrap the same proven connectors that power some of t
 
 With over 300 connectors and real-time debugging capabilities, you reduce integration time while getting enterprise-grade security. You can reuse your existing infrastructure and data sources rather than building new integrations from scratch.
 
-For more information, see xref:mcp:overview.adoc[MCP Servers Overview].
+For more information, see xref:mcp:index.adoc[MCP Servers Overview].
 
 == Transcripts
 
@@ -85,6 +85,6 @@ Some ways organizations can leverage Redpanda ADP include:
 == Next steps
 
 * xref:agents:overview.adoc[AI Agents Overview]
-* xref:mcp:overview.adoc[MCP Server Overview]
+* xref:mcp:index.adoc[MCP Server Overview]
 * xref:observability:concepts.adoc[Transcripts Overview]
 * xref:ai-gateway:overview.adoc[AI Gateway Overview]

modules/agents/pages/architecture-patterns.adoc

@@ -167,7 +167,7 @@ This pattern fails because:
 * Tool descriptions compete for limited prompt space
 * The agent invokes wrong tools with similar names, wasting iteration budget on selection mistakes
 
-Limit tools per agent to 10-15 for optimal performance. Agents with more than 20-25 tools often show degraded tool selection accuracy. Use subagents to partition tools by domain. For tool design patterns, see xref:mcp:remote/patterns.adoc[].
+Limit tools per agent to 10-15 for optimal performance. Agents with more than 20-25 tools often show degraded tool selection accuracy. Use subagents to partition tools by domain. For tool design patterns, see xref:mcp:index.adoc[].
 
 === Premature A2A splitting
 
@@ -259,6 +259,6 @@ Provide clear error messages to users. Log errors for debugging.
 
 * xref:integration-overview.adoc[]
 * xref:a2a-concepts.adoc[]
-* xref:mcp:remote/patterns.adoc[]
+* xref:mcp:index.adoc[]
 * xref:overview.adoc[]
-* xref:mcp:remote/best-practices.adoc[]
+* xref:mcp:index.adoc[]

modules/agents/pages/concepts.adoc

@@ -132,7 +132,7 @@ Tool design affects agent behavior. Coarse-grained tools that do many things res
 
 Choose granularity based on how often you'll reuse tool logic across workflows, whether intermediate results help with debugging, and how much control you want over tool invocation order.
 
-For tool design guidance, see xref:mcp:remote/best-practices.adoc[].
+For tool design guidance, see xref:mcp:index.adoc[].
 
 == Context and state management
 
@@ -159,4 +159,4 @@ include::ROOT:partial$service-account-authorization.adoc[]
 * xref:architecture-patterns.adoc[]
 * xref:quickstart.adoc[]
 * xref:system-prompts.adoc[]
-* xref:mcp:remote/best-practices.adoc[]
+* xref:mcp:index.adoc[]

modules/agents/pages/create-agent.adoc

@@ -20,7 +20,7 @@ After reading this page, you will be able to:
 
 * A xref:redpanda-cloud:get-started:cluster-types/byoc/index.adoc[BYOC cluster].
 * xref:ai-gateway:gateway-quickstart.adoc[AI Gateway configured] with at least one LLM provider enabled.
-* At least one xref:mcp:remote/overview.adoc[Remote MCP server] deployed with tools.
+* At least one xref:mcp:index.adoc[Remote MCP server] deployed with tools.
 * System prompt prepared (see xref:system-prompts.adoc[System Prompt Best Practices]).
 
 == Access the agents UI
@@ -276,6 +276,6 @@ Here are example configurations for different agent types:
 
 * xref:integration-overview.adoc[]
 * xref:system-prompts.adoc[]
-* xref:mcp:remote/create-tool.adoc[]
+* xref:mcp:create-server.adoc[]
 * xref:architecture-patterns.adoc[]
 * xref:troubleshoot.adoc[]

modules/agents/pages/integration-overview.adoc

@@ -27,7 +27,7 @@ Redpanda Cloud supports three primary integration scenarios based on who initiat
 | Agent needs capabilities
 | Your agent invokes MCP tools to fetch data, call APIs, or access external systems on-demand
 | Agent-initiated, synchronous, interactive workflows
-| xref:mcp:remote/patterns.adoc[]
+| xref:mcp:index.adoc[]
 
 | Pipeline processes events
 | Your Redpanda Connect pipeline invokes agents for each event in a stream using the `a2a_message` processor
@@ -55,7 +55,7 @@ This pattern works well for interactive workflows: customer support lookups, app
 
 Avoid MCP tools for high-volume stream processing or automated workflows without user interaction. Use pipeline-initiated integration instead.
 
-For implementation details, see xref:mcp:remote/patterns.adoc[].
+For implementation details, see xref:mcp:index.adoc[].
 
 [[pipeline-processes-events]]
 === Pipeline processes events (`a2a_message`)
@@ -126,5 +126,5 @@ Access tokens grant full access to the agent. Anyone with a valid token can send
 == Next steps
 
 * xref:a2a-concepts.adoc[]
-* xref:mcp:remote/patterns.adoc[]
+* xref:mcp:index.adoc[]
 * xref:pipeline-integration-patterns.adoc[]

modules/agents/pages/overview.adoc

@@ -27,7 +27,7 @@ When you create an agent, you configure the components through the Redpanda Clou
 
 * *System prompt*: Defines the agent's role, responsibilities, and constraints
 * *LLM*: Interprets user intent and decides which tools to invoke
-* *Tools*: External capabilities exposed through the xref:mcp:remote/overview.adoc[Model Context Protocol (MCP)]
+* *Tools*: External capabilities exposed through the xref:mcp:index.adoc[Model Context Protocol (MCP)]
 * *Context*: Conversation history, tool results, and real-time events from Redpanda topics
 
 Agents can invoke Redpanda Connect components as tools on-demand. Redpanda Connect pipelines can also invoke agents for event-driven processing. This bidirectional integration supports both interactive workflows and automated streaming.
@@ -38,7 +38,7 @@ For a deeper understanding of how agents execute, manage context, and maintain s
 
 == Key benefits
 
-A declarative approach means you configure agent behavior instead of coding it, with access to 300+ built-in Redpanda Connect connectors for data sources, APIs, and services. Real-time streaming data ensures agents access live events instead of batch snapshots. xref:mcp:remote/overview.adoc[Remote MCP] support enables standardized tool access. Managed infrastructure handles deployment, scaling, and security for you. Low-latency execution means tools run close to your data. Integrated secrets management securely stores API keys and credentials.
+A declarative approach means you configure agent behavior instead of coding it, with access to 300+ built-in Redpanda Connect connectors for data sources, APIs, and services. Real-time streaming data ensures agents access live events instead of batch snapshots. xref:mcp:index.adoc[Remote MCP] support enables standardized tool access. Managed infrastructure handles deployment, scaling, and security for you. Low-latency execution means tools run close to your data. Integrated secrets management securely stores API keys and credentials.
 
 == Use cases
 

modules/agents/pages/pipeline-integration-patterns.adoc

@@ -139,7 +139,7 @@ This pipeline:
 
 == Next steps
 
-* xref:mcp:remote/patterns.adoc[]
+* xref:mcp:index.adoc[]
 * xref:integration-overview.adoc[]
 * xref:a2a-concepts.adoc[]
 * xref:redpanda-cloud:develop:connect/components/processors/about.adoc[]

modules/agents/pages/quickstart.adoc

@@ -23,7 +23,7 @@ After completing this quickstart, you will be able to:
 
 * xref:ai-gateway:gateway-quickstart.adoc[AI Gateway configured] with at least one LLM provider enabled (OpenAI, Anthropic, or Google AI)
 
-* Completed the xref:mcp:remote/quickstart.adoc[Remote MCP Quickstart] to create an MCP server with the following tools deployed:
+* Completed the xref:mcp:create-server.adoc[Remote MCP Quickstart] to create an MCP server with the following tools deployed:
 +
 ** `generate_input`: Generates fake user event data
 ** `redpanda_output`: Publishes data to Redpanda topics
@@ -185,4 +185,4 @@ You've created an agent that orchestrates MCP tools through natural language. Ex
 * xref:create-agent.adoc[]
 * xref:system-prompts.adoc[]
 * xref:architecture-patterns.adoc[]
-* xref:mcp:remote/patterns.adoc[]
+* xref:mcp:index.adoc[]