Doc 1846: Remote MCP GA #472
Conversation
- Change MCP API paths from /v1/mcp_servers to /v1/redpanda-connect/mcp-servers - Fix serverless cluster path from /v1/serverless-clusters to /v1/serverless/clusters - Add note about Data Plane API URL availability timing (5-10 minute delay) - Add required service_account field to MCP server creation example
- Restructure admin-guide.adoc as navigation hub - Create manage-servers.adoc for lifecycle management (edit, stop, start, delete) - Create scale-resources.adoc for resource allocation and cost optimization - Create monitor-activity.adoc for OpenTelemetry traces and observability - Add Grafana Cloud integration example to monitoring documentation - Update navigation to show hierarchical structure with three child pages This improves information architecture and user experience by organizing content by specific tasks rather than mixing multiple topics in one page.
- Add pattern selection guide at top for quick navigation - Add 'When to use' and 'Example use cases' to all patterns - Add new pattern sections: * Data generators (generate input for testing) * Data consumers (reading from Redpanda topics) * Data transformation (Bloblang mapping examples) * AI/LLM integration (OpenAI chat completion and embeddings) - Fix deprecated kafka_franz component, use redpanda input instead - Remove unnecessary manual anchor IDs (Antora generates them automatically) - Restructure Redpanda integration section with proper hierarchy These improvements make the patterns catalog more discoverable and provide clearer guidance on when to use each pattern.
Prevent environment files from being committed to repository.
AsciiDoc formatting: escape curly braces in inline code blocks to prevent them from being interpreted as attribute references.
- Change heading to 'OpenTelemetry traces topic' for clarity - Document auto-created Protobuf schema 'redpanda.otel_traces-value' - Update trace data structure example with realistic values (hex IDs, numeric enums) - Refine field descriptions and reference schema for details - Remove Custom dashboards and Best practices sections (too implementation-specific)
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
- Add npm install step to install @redpanda-data/docs-extensions-and-macros - Use --no-install flag with npx to prevent trying to download from npm - The doc-tools binary is provided by @redpanda-data/docs-extensions-and-macros
- Add MCP_FAILS counter to track validation failures - Remove '|| true' that was suppressing validation failures - Increment MCP_FAILS when validate_mcp_metadata returns non-zero - Display MCP validation failures in test summary - Exit with non-zero code when MCP validations fail This ensures missing descriptions or other MCP metadata issues cause the GitHub Actions workflow to fail.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
modules/ai-agents/pages/index.adoc (1)
10-10: Verify badge attribute consistency across pages.Line 10 uses the same
{page-beta-text}attribute asoverview.adoc. Ensure this attribute is globally available so both pages render consistently.The verification requested in the
overview.adocreview comment will cover this attribute as well.
🧹 Nitpick comments (2)
modules/ai-agents/examples/test-mcp-examples.sh (2)
65-66: Separate variable declaration and assignment to improve error detection.Combining
localwith command substitution masks the return value ofgrep. Shellcheck recommends declaring the variable first, then assigning it separately.Apply this diff:
- local has_enabled=$(grep -c "enabled: true" "$file" || echo 0) - local has_description=$(grep -c "description:" "$file" || echo 0) + local has_enabled + has_enabled=$(grep -c "enabled: true" "$file" || echo 0) + local has_description + has_description=$(grep -c "description:" "$file" || echo 0)
32-49: Add pre-flight checks to improve script robustness.The script assumes
rpk connect lintis available and that files exist before attempting to validate them. Consider adding defensive checks.Add these checks near the beginning of the script, after the shebang and color definitions:
+# Check for required tools +if ! command -v rpk &> /dev/null; then + echo -e "${RED}Error: rpk command not found. Please ensure Redpanda CLI is installed.${NC}" + exit 1 +fi + +# Validate that at least one file matches the pattern +if ! ls $PATTERN 1> /dev/null 2>&1; then + echo -e "${YELLOW}Warning: No files matching pattern '$PATTERN' found${NC}" + exit 0 +fi
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (20)
.github/workflows/test-mcp-examples.yaml(1 hunks).github/workflows/update-extensions.yml(1 hunks).gitignore(1 hunks)local-antora-playbook.yml(1 hunks)modules/ROOT/nav.adoc(1 hunks)modules/ai-agents/examples/test-mcp-examples.sh(1 hunks)modules/ai-agents/examples/testing.adoc(1 hunks)modules/ai-agents/pages/index.adoc(1 hunks)modules/ai-agents/pages/mcp/overview.adoc(1 hunks)modules/ai-agents/pages/mcp/remote/admin-guide.adoc(1 hunks)modules/ai-agents/pages/mcp/remote/developer-guide.adoc(3 hunks)modules/ai-agents/pages/mcp/remote/index.adoc(0 hunks)modules/ai-agents/pages/mcp/remote/manage-servers.adoc(1 hunks)modules/ai-agents/pages/mcp/remote/monitor-activity.adoc(1 hunks)modules/ai-agents/pages/mcp/remote/overview.adoc(2 hunks)modules/ai-agents/pages/mcp/remote/pipeline-patterns.adoc(3 hunks)modules/ai-agents/pages/mcp/remote/quickstart.adoc(6 hunks)modules/ai-agents/pages/mcp/remote/scale-resources.adoc(1 hunks)modules/billing/pages/billing.adoc(1 hunks)modules/get-started/pages/whats-new-cloud.adoc(1 hunks)
💤 Files with no reviewable changes (1)
- modules/ai-agents/pages/mcp/remote/index.adoc
🧰 Additional context used
🧠 Learnings (4)
📓 Common learnings
Learnt from: micheleRP
Repo: redpanda-data/cloud-docs PR: 377
File: modules/networking/pages/dedicated/gcp/configure-psc-in-ui.adoc:35-71
Timestamp: 2025-08-07T16:36:45.111Z
Learning: In Redpanda Cloud documentation, NAT subnet and firewall rule creation commands for GCP Private Service Connect are producer-side infrastructure steps that only BYOC (Bring Your Own Cloud) customers need to perform, since they manage their own VPC. Dedicated cluster customers don't need these steps because Redpanda manages the infrastructure for them. The ifdef::env-byoc[] guard correctly hides these commands from Dedicated users.
Learnt from: micheleRP
Repo: redpanda-data/cloud-docs PR: 390
File: modules/manage/pages/schema-reg/schema-reg-authorization.adoc:4-4
Timestamp: 2025-08-15T02:29:34.901Z
Learning: In Redpanda Cloud documentation PRs, when CodeRabbit flags missing Asciidoctor tag markers for include directives, the fix may be implemented in the corresponding ROOT module file that contains the actual content being included, rather than in the file where the include directive appears.
📚 Learning: 2025-08-15T04:45:28.695Z
Learnt from: micheleRP
Repo: redpanda-data/cloud-docs PR: 390
File: modules/manage/pages/schema-reg/schema-reg-authorization.adoc:4-4
Timestamp: 2025-08-15T04:45:28.695Z
Learning: In the Redpanda documentation system, content is single-sourced across multiple repositories (cloud-docs and docs repos). Include directives in the cloud-docs repo may reference files that exist in separate PRs in the docs repo. These PRs are linked via local-antora-playbook.yml for preview rendering, and the includes resolve correctly during the Antora build process when repositories are merged. The playbook is reverted to main before merging. This cross-repository single sourcing pattern is commonly used, so missing include targets should be verified against linked PRs in other repositories before flagging as errors.
Applied to files:
local-antora-playbook.yml
📚 Learning: 2025-04-25T01:42:09.318Z
Learnt from: micheleRP
Repo: redpanda-data/cloud-docs PR: 267
File: modules/manage/pages/maintenance.adoc:63-64
Timestamp: 2025-04-25T01:42:09.318Z
Learning: The timeline for major upgrade notifications (180 days in advance) was intentionally removed from the Redpanda Cloud maintenance documentation, even though it was mentioned in the PR objectives.
Applied to files:
modules/get-started/pages/whats-new-cloud.adoc
📚 Learning: 2025-08-07T16:36:45.111Z
Learnt from: micheleRP
Repo: redpanda-data/cloud-docs PR: 377
File: modules/networking/pages/dedicated/gcp/configure-psc-in-ui.adoc:35-71
Timestamp: 2025-08-07T16:36:45.111Z
Learning: In Redpanda Cloud documentation, NAT subnet and firewall rule creation commands for GCP Private Service Connect are producer-side infrastructure steps that only BYOC (Bring Your Own Cloud) customers need to perform, since they manage their own VPC. Dedicated cluster customers don't need these steps because Redpanda manages the infrastructure for them. The ifdef::env-byoc[] guard correctly hides these commands from Dedicated users.
Applied to files:
modules/ai-agents/pages/mcp/remote/developer-guide.adoc
🪛 Shellcheck (0.11.0)
modules/ai-agents/examples/test-mcp-examples.sh
[warning] 65-65: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 66-66: Declare and assign separately to avoid masking return values.
(SC2155)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - rp-cloud
- GitHub Check: Header rules - rp-cloud
- GitHub Check: Pages changed - rp-cloud
🔇 Additional comments (33)
.gitignore (1)
11-11: LGTM!Adding
.envto.gitignoreis appropriate for environment variable files, especially given the new CI workflows and example testing infrastructure..github/workflows/update-extensions.yml (1)
35-35: Consistent Node.js version bump across CI workflows.The update to Node.js 22 aligns with the same change in
test-mcp-examples.yaml. The verification requested fortest-mcp-examples.yamlregarding Node.js 22 stability will apply here as well.modules/ai-agents/pages/mcp/remote/overview.adoc (2)
32-38: LGTM: Authentication section with MCP proxy guidance is clear.The authentication section correctly recommends the MCP proxy approach for Claude Code and provides practical
rpkcommand guidance. The direct connection option is also documented for custom implementations.
19-19: Verify cross-repository includes are available before playbook revert.This file includes three partials from
redpanda-connect:ai-agents:partial$mcp/on lines 19, 28, and 43 (use-cases-table.adoc,customer-analytics-example.adoc,specification-support.adoc). These includes depend on thelocal-antora-playbook.ymlconfiguration and must resolve after the playbook is reverted tomain.Coordinate with rp-connect-docs maintainers to confirm these partials are available in the target branch before merging, or ensure a linked PR in rp-connect-docs addresses these files.
modules/ai-agents/pages/mcp/remote/scale-resources.adoc (2)
4-4: Verify cross-reference links to billing and quickstart pages.Lines 4, 8, and 62 reference:
xref:billing:billing.adoc#remote-mcp-billing-metrics(lines 4, 62)xref:ai-agents:mcp/remote/quickstart.adoc(line 8)Confirm these pages exist and the anchors/paths are correct.
36-57: Verify Data Plane API endpoint operations and field names.Lines 36-38 reference specific Data Plane API operations and field names. The curl example uses
memory_sharesandcpu_shares— these field names are valid in the Redpanda Cloud API for resource configuration. However, the specific operation IDs (operation-mcpserverservice_getmcpserver,operation-mcpserverservice_updatemcpserver) and whether the PATCH method is correct for the/v1/redpanda-connect/mcp-servers/{mcp_server_id}endpoint could not be conclusively verified from available sources.Confirm against the official Redpanda Cloud Data Plane API documentation that:
- The exact operation IDs match those in the API reference
- The endpoint paths and HTTP methods (GET and PATCH) are accurate for the mcp-servers resource
- The
update_maskfield and resource object structure align with the API schema.github/workflows/test-mcp-examples.yaml (3)
37-40: Verify test script exists and is executable in target directory.Lines 37-40 change directory to
modules/ai-agents/examplesand execute./test-mcp-examples.sh. Ensure this script is present in the repository and properly implements MCP example validation.
26-29: Verify Node.js 22 LTS status and project compatibility.Node.js 22 is specified in both
test-mcp-examples.yaml(line 29) andupdate-extensions.yml, confirming version consistency across workflows. Thepackage.jsoncontains no explicit Node.js engine constraints, allowing flexible version support. Confirm that Node.js 22 is production-ready and compatible with project dependencies, particularly@redpanda-data/docs-extensions-and-macros(^4.0.0).
32-32: The code snippet and line reference in this review comment are incorrect. Line 32 containsrun: npm install, while thedoc-tools install-test-dependenciescommand is actually on line 35 withrun: npx --no-install doc-tools install-test-dependencies.The actual implementation is correct:
doc-toolsis properly available as a transitive dependency through@redpanda-data/docs-extensions-and-macros(v4.12.5), and the--no-installflag ensures npx uses the already-installed package from the priornpm installstep. No action is required.Likely an incorrect or invalid review comment.
modules/ai-agents/pages/mcp/overview.adoc (1)
17-17: The{page-beta-text}attribute is provided by the@redpanda-data/docs-extensions-and-macrosextension (specifically theadd-global-attributesextension loaded in the Antora playbook). This syntax is already in use elsewhere in the repository (modules/ai-agents/pages/index.adoc) and works correctly, confirming the attribute is properly defined in the build context.local-antora-playbook.yml (1)
26-26: Thesingle-sourcebranch reference for rp-connect-docs is part of Redpanda's cross-repository single-sourcing pattern and will be reverted tomainper the standard workflow before this PR merges. The includes inoverview.adocandpipeline-patterns.adoc(such asredpanda-connect:ai-agents:partial$mcp/use-cases-table.adoc) are correctly configured for the coordinated multi-repo build process.modules/ai-agents/pages/mcp/remote/manage-servers.adoc (1)
1-8: Excellent lifecycle management documentation.The structure is clear, with well-organized tabs for both Cloud UI and API approaches. Prerequisites are properly stated, and the cross-references to related guides are appropriate.
modules/ai-agents/examples/testing.adoc (2)
61-66: Excellent clarification on unit testing limitations.The IMPORTANT note correctly explains why MCP tool examples cannot use inline
tests:sections—they are standalone component definitions, not full pipelines with input/pipeline/output structure. This is an important distinction for users who may be familiar with cookbook examples.
168-237: Best practices section is comprehensive and actionable.The guidance on naming, descriptions, properties, secrets management, tagging, and adding new examples provides clear direction for contributors. Examples effectively demonstrate good vs. bad patterns.
modules/billing/pages/billing.adoc (1)
113-141: Clear and consistent compute unit pricing definition.The addition of compute unit metrics for both Redpanda Connect and Remote MCP is well-structured. The definition (1 compute unit = 0.1 CPU + 400 MB memory) is consistent across both sections, and the NOTE on line 141 properly clarifies that MCP uses the same units and rates as Connect.
modules/ai-agents/pages/mcp/remote/admin-guide.adoc (2)
1-4: Strong refactoring from task-oriented to navigation-focused guide.The shift from providing step-by-step instructions inline to directing users to dedicated guides (manage-servers, scale-resources, monitor-activity) reduces duplication and improves content organization. The high-level overview approach is well-suited for an admin guide.
47-69: No action needed. The Data Plane API endpoint references in this section are current and correctly documented. The operation identifiers and link format follow Redpanda's established conventions and are consistently used across multiple MCP documentation files.modules/ai-agents/pages/mcp/remote/monitor-activity.adoc (2)
1-23: Excellent comprehensive monitoring documentation.This guide provides clear guidance on consuming and analyzing OpenTelemetry traces from Remote MCP servers. The structure flows logically from trace topic overview, to consumption methods, to data structure details, and finally to monitoring scenarios and platform integrations.
104-163: Real trace examples effectively demonstrate parent-child relationships.The actual trace examples for successful execution and error scenarios are realistic and well-annotated. The explanation of traceId, spanId, and parentSpanId relationships (lines 160-163) helps readers understand distributed tracing concepts. The duration calculation example is particularly useful for performance analysis.
modules/ROOT/nav.adoc (1)
83-85: Navigation structure properly organizes new admin guides.The three new sub-items (Manage Servers, Scale Resources, Monitor Activity) are correctly placed as children of the Admin Guide with proper indentation and xref syntax. This creates a logical navigation hierarchy for Remote MCP administrative tasks.
However, note that
scale-resources.adocis referenced here but not included in the provided files. Please confirm this file is included in the full PR.modules/ai-agents/pages/mcp/remote/pipeline-patterns.adoc (3)
11-22: Pattern selection guide provides excellent user navigation.The new "Pattern selection guide" with bullet-point linking to pattern anchors helps users quickly find the right pattern for their use case. This is a significant usability improvement over the previous organization.
207-215: Verify external partial includes are properly configured in documentation build.Lines 209, 212, and 215 use
include::redpanda-connect:ai-agents:partial$syntax to source content from the redpanda-connect module documentation. This is a single-source reuse pattern that depends on proper Antora configuration.Please verify:
- The
redpanda-connectcomponent is properly defined in the Antora playbook- The partial paths exist in the redpanda-connect documentation:
modules/ai-agents/partials/mcp/production-workflows-before-secrets.adocmodules/ai-agents/partials/mcp/secrets-cloud.adocmodules/ai-agents/partials/mcp/production-workflows-after-secrets.adocThis may be addressed by other files in the full PR, but the include statements should be verified against the actual file structure.
36-36: All referenced example YAML files exist inmodules/ai-agents/examples/and will resolve correctly with theinclude::ai-agents:example$syntax.modules/get-started/pages/whats-new-cloud.adoc (1)
11-13: New Remote MCP GA entry is well-placed and clearly written.The Remote MCP GA announcement in December 2025 appropriately supersedes the beta announcement from October. The description concisely conveys the value proposition and the xref link structure is sound.
Ensure the xref target
xref:ai-agents:mcp/remote/overview.adocexists and is included in this PR.modules/ai-agents/pages/mcp/remote/developer-guide.adoc (4)
28-96: Well-structured workflow and comprehensive tags guidance.The reordered development workflow places metadata configuration first (more intuitive for GA), and the new "Organize servers with tags" section provides practical tagging strategies and clearly documents reserved tag names. The section anchors are properly set for cross-referencing.
Verify that the Server Metadata fields listed at lines 47–51 (Display Name, Description, Tags, Resources, Service Account) match the actual Redpanda Cloud UI for GA release, and confirm that the reserved tag names at lines 87–88 are enforced by the backend.
97-166: Contract design and secrets management sections are thorough and security-focused.The MCP metadata YAML example with annotations is clear, property guidance addresses component-type restrictions, and the secrets section emphasizes best practices (no hardcoding, rotation, least privilege). The inline secret creation workflow balances convenience with the manual Secrets Store option.
Verify that the xref target
xref:ai-agents:mcp/remote/pipeline-patterns.adoc#secretsexists and contains a secrets example, and confirm that the component-type restrictions described at line 138 (e.g., input components only supportcountproperty) match the actual Redpanda Connect behavior.
169-282: Comprehensive tool building guidance with clear examples and best practices.The "Build your MCP tool" section provides solid best-practices guidance (single responsibility, input validation, error handling), clear YAML configuration rules, and helpful correct/incorrect examples. The property restrictions table by component type is well-structured.
Verify that the included example file
modules/ai-agents/examples/weather_service.yamlexists and is a valid Redpanda Connect tool, and confirm that the component-type property restrictions in the table (lines 201–220) accurately reflect current Redpanda Connect behavior (e.g., input components only supportingcountproperty, cache components having no custom properties).
284-392: Clear deployment, testing, and authentication workflows.The "Lint and deploy" section provides a comprehensive checklist (YAML syntax, component schema, MCP metadata, secrets formatting), and the "Authenticate and connect" section properly distinguishes between BYOC/Dedicated (cluster-id) and Serverless (serverless-cluster-id) command variants. The note about building a custom agent is helpful context.
Ensure the placeholder syntax for
<cluster-id>and<server-id>in the commands at lines 355–368 is clear to users. Consider addingrole=no-placeholdersto the code block to help users distinguish between literal command text and values they need to substitute.modules/ai-agents/pages/mcp/remote/quickstart.adoc (5)
38-133: Comprehensive cluster prep with both rpk and API approaches; good practical notes on API latency.The two-tab structure provides both quick (rpk) and programmatic (API) paths. The Data Plane API tab includes helpful notes about token expiry (line 71) and dataplane_api.url latency (lines 114–115), which reflect real operational pain points. The JSON payload for topic creation is clear.
Verify that the API endpoint links at lines 80, 94, and 117 resolve correctly (e.g.,
link:/api/doc/cloud-controlplane/operation/operation-clusterservice_getcluster), and confirm that the API response structure shown at lines 102–110 (withdataplane_api.urlfield) matches the actual Control Plane API response for both BYOC/Dedicated and Serverless clusters.
135-185: Clear Cloud UI walkthrough with proper field guidance and service account explanation.The Cloud UI tab provides step-by-step guidance with proper descriptions of Server Metadata fields and a helpful note about automatic service account creation (lines 156–159). The template dropdown approach is practical, and MCP Inspector testing guidance is clear.
233-308: Clear client connection workflow with good example requests and verification.The "Connect an AI client" section properly explains MCP discovery and tool invocation (lines 237–242), provides distinct command variants for cluster types (lines 259–274), includes practical example requests showing variety of use cases, and concludes with a verification step (consume from topic). Token validity notes are consistent.
314-352: Practical troubleshooting and clear next steps.The troubleshooting subsections address common scenarios (server not starting, connection issues, publishing failures) with specific diagnostic commands. Next steps appropriately point to the developer guide and list concrete use case categories for exploration.
1-36: Content is well-structured, but the beta flag is appropriate for the current product status.The "What you'll learn" and "How MCP works" sections clearly introduce MCP concepts, and the prerequisites are comprehensive with the correct rpk version 25.2.5 specification. The
:page-beta: trueattribute on line 2 should remain, as Remote MCP Server is still in beta according to Redpanda's official documentation—not a GA release yet. The page structure and content are accurate and ready for publication.
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
modules/ai-agents/pages/mcp/remote/pipeline-patterns.adoc (2)
1-5: Remove:page-beta: trueattribute to align with GA objectives.The file still declares
:page-beta: trueon line 3, but PR objectives explicitly state: "Remove any beta labels from Remote MCP documentation." This attribute must be removed for the Remote MCP GA release.Apply this diff to remove the beta attribute:
= Patterns for Remote MCP Servers :description: Catalog of patterns for Remote MCP server tools in Redpanda Cloud. -:page-beta: true
30-36: Add missing#secretsanchor to pipeline-patterns.adoc.The file
developer-guide.adocline 166 referencesxref:ai-agents:mcp/remote/pipeline-patterns.adoc#secrets[MCP patterns], but the#secretsanchor does not exist in pipeline-patterns.adoc. All example YAML includes (generate_input.yaml, http_processor.yaml, etc.) are correctly present and will resolve. However, the broken cross-reference to the missing anchor will cause documentation build failures.
🧹 Nitpick comments (2)
modules/ai-agents/examples/test-mcp-examples.sh (2)
65-66: Fix SC2155: Declare and assign separately for proper error capture.Shellcheck warns that combining local declaration and assignment masks the return value of the command. Separate these into two statements to allow proper error handling.
- local has_enabled=$(grep -c "enabled: true" "$file" || echo 0) - local has_description=$(grep -c "description:" "$file" || echo 0) + local has_enabled + has_enabled=$(grep -c "enabled: true" "$file" || echo 0) + local has_description + has_description=$(grep -c "description:" "$file" || echo 0)
39-41: Consider checking exit codes directly instead of parsing output.The current approach greps for "error" in rpk output and then repeats the lint command. This is fragile and redundant. Consider capturing the exit code directly:
- if rpk connect lint --skip-env-var-check "$file" 2>&1 | grep -q "error"; then + if ! rpk connect lint --skip-env-var-check "$file" > /tmp/lint-out.txt 2>&1; then echo -e "${RED}FAILED${NC}" - rpk connect lint --skip-env-var-check "$file" 2>&1 | sed 's/^/ /' + cat /tmp/lint-out.txt | sed 's/^/ /' FAILED=$((FAILED + 1)) return 1This avoids:
- Redundant lint invocation
- Output parsing brittleness
- Reliance on specific error message format
Verify that rpk connect lint returns non-zero exit code on validation errors, as this change assumes.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (20)
.github/workflows/test-mcp-examples.yaml(1 hunks).github/workflows/update-extensions.yml(1 hunks).gitignore(1 hunks)local-antora-playbook.yml(1 hunks)modules/ROOT/nav.adoc(1 hunks)modules/ai-agents/examples/test-mcp-examples.sh(1 hunks)modules/ai-agents/examples/testing.adoc(1 hunks)modules/ai-agents/pages/index.adoc(1 hunks)modules/ai-agents/pages/mcp/overview.adoc(1 hunks)modules/ai-agents/pages/mcp/remote/admin-guide.adoc(1 hunks)modules/ai-agents/pages/mcp/remote/developer-guide.adoc(3 hunks)modules/ai-agents/pages/mcp/remote/index.adoc(0 hunks)modules/ai-agents/pages/mcp/remote/manage-servers.adoc(1 hunks)modules/ai-agents/pages/mcp/remote/monitor-activity.adoc(1 hunks)modules/ai-agents/pages/mcp/remote/overview.adoc(2 hunks)modules/ai-agents/pages/mcp/remote/pipeline-patterns.adoc(3 hunks)modules/ai-agents/pages/mcp/remote/quickstart.adoc(6 hunks)modules/ai-agents/pages/mcp/remote/scale-resources.adoc(1 hunks)modules/billing/pages/billing.adoc(1 hunks)modules/get-started/pages/whats-new-cloud.adoc(1 hunks)
💤 Files with no reviewable changes (1)
- modules/ai-agents/pages/mcp/remote/index.adoc
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2025-08-01T16:52:49.111Z
Learnt from: micheleRP
Repo: redpanda-data/cloud-docs PR: 370
File: modules/security/pages/cloud-authentication.adoc:68-70
Timestamp: 2025-08-01T16:52:49.111Z
Learning: In the Redpanda Cloud documentation using Antora, the badge macro with double colon syntax `badge::[label=beta, tooltip={page-beta-text}]` works correctly when used inline within AsciiDoc section headings and displays the beta badge in the right-side navigation along with the heading title.
Applied to files:
modules/ai-agents/pages/index.adoc
📚 Learning: 2025-08-15T04:45:28.695Z
Learnt from: micheleRP
Repo: redpanda-data/cloud-docs PR: 390
File: modules/manage/pages/schema-reg/schema-reg-authorization.adoc:4-4
Timestamp: 2025-08-15T04:45:28.695Z
Learning: In the Redpanda documentation system, content is single-sourced across multiple repositories (cloud-docs and docs repos). Include directives in the cloud-docs repo may reference files that exist in separate PRs in the docs repo. These PRs are linked via local-antora-playbook.yml for preview rendering, and the includes resolve correctly during the Antora build process when repositories are merged. The playbook is reverted to main before merging. This cross-repository single sourcing pattern is commonly used, so missing include targets should be verified against linked PRs in other repositories before flagging as errors.
Applied to files:
local-antora-playbook.yml
📚 Learning: 2025-08-07T16:36:45.111Z
Learnt from: micheleRP
Repo: redpanda-data/cloud-docs PR: 377
File: modules/networking/pages/dedicated/gcp/configure-psc-in-ui.adoc:35-71
Timestamp: 2025-08-07T16:36:45.111Z
Learning: In Redpanda Cloud documentation, NAT subnet and firewall rule creation commands for GCP Private Service Connect are producer-side infrastructure steps that only BYOC (Bring Your Own Cloud) customers need to perform, since they manage their own VPC. Dedicated cluster customers don't need these steps because Redpanda manages the infrastructure for them. The ifdef::env-byoc[] guard correctly hides these commands from Dedicated users.
Applied to files:
modules/ai-agents/pages/mcp/remote/developer-guide.adocmodules/get-started/pages/whats-new-cloud.adoc
🪛 Shellcheck (0.11.0)
modules/ai-agents/examples/test-mcp-examples.sh
[warning] 65-65: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 66-66: Declare and assign separately to avoid masking return values.
(SC2155)
🔇 Additional comments (16)
.gitignore (1)
11-11: Well-placed security improvement.Adding
.envto.gitignoreis a sensible safeguard for the new test infrastructure introduced in this PR. This prevents accidental commits of environment-specific configuration and credentials, aligning with the addition of the test-mcp-examples.sh script and GitHub Actions workflows.modules/ai-agents/pages/index.adoc (1)
10-10: LGTM: Badge macro migration is correct.The inline badge macro correctly replaces the page-beta metadata and will render properly in the navigation and heading. This aligns with the documented pattern from previous PRs.
modules/ai-agents/pages/mcp/overview.adoc (1)
17-17: LGTM: Badge macro in table header is correct.The inline badge macro in the table column header will render properly and clearly marks the MCP Server as beta. Consistent with the pattern used in other pages.
modules/get-started/pages/whats-new-cloud.adoc (1)
11-13: LGTM: Remote MCP GA announcement is clear and well-placed.The announcement correctly describes the feature, includes the xref reference to the overview documentation, and acknowledges the shift from beta to GA. Chronologically appropriate placement in December 2025 section.
.github/workflows/update-extensions.yml (1)
35-35: LGTM: Node.js version update aligns with new tooling.Updated to Node.js 22, which is consistent with the new MCP testing workflow and supports the latest docs-extensions-and-macros tooling. This change is necessary and appropriate.
modules/ROOT/nav.adoc (1)
83-85: Navigation references verified. All three target files exist in the repository:
modules/ai-agents/pages/mcp/remote/manage-servers.adoc✓modules/ai-agents/pages/mcp/remote/scale-resources.adoc✓modules/ai-agents/pages/mcp/remote/monitor-activity.adoc✓No broken navigation references detected.
modules/ai-agents/pages/mcp/remote/developer-guide.adoc (6)
1-40: Workflow structure and prerequisites look solid.Clear prerequisites, comprehensive workflow overview, and proper cross-references. Section anchors and xrefs are consistent.
38-96: Server creation and tagging sections are well-structured and actionable.The metadata configuration flow is clear, automatic service account creation is explicitly stated (addressing PR objectives), and the tagging guidance with strategy examples and reserved names is practical and complete.
97-220: Tool contract design and YAML configuration guidance is thorough and well-exemplified.The property guidance, component type restrictions table, and correct/incorrect examples are clear. The forward reference to component restrictions at line 138 could ideally be placed immediately before the detailed table (line 188+), but the content is discoverable and complete.
142-178: Secrets provisioning and tool building sections are clear and best-practice-focused.Inline secret creation workflow and best practices are well-explained. The reference at line 166 to
pipeline-patterns.adoc#secretsneeds verification that the anchor exists in that file.
283-332: Deployment, testing, and management workflows are well-documented and actionable.Linting checklist is comprehensive, status indicators are clear, MCP Inspector workflow is explained, and management operations are listed. Reference to admin-guide is consistent with PR scope.
335-392: Authentication workflow properly handles cluster-type variations.Clear differentiation between BYOC/Dedicated and Serverless clusters with explicit commands, helpful context in TIP and NOTE boxes, and clear guidance that rpk is optional. Section is well-structured and complete.
modules/ai-agents/pages/mcp/remote/pipeline-patterns.adoc (4)
71-159: New data transformation and AI/LLM integration sections are well-structured and timely.The data consumers section is clearly presented with Redpanda configuration details. Data transformation and AI/LLM integration patterns (including OpenAI chat completion and embeddings) are new, valuable additions for the GA release. Content is clear and examples are appropriately formatted.
160-205: Redpanda integration section consolidates publishers and caching logically.New grouping of data publishers and caching systems under "Redpanda integration" makes architectural sense. Descriptions and use cases are clear. Multiple example includes need file existence verification.
207-215: Partials-based approach supports documentation reuse objective.The three includes from
redpanda-connect:ai-agents:partial$promote single-source documentation reuse from self-managed Redpanda Connect docs, aligning with PR objectives. Comments clearly explain the intent (before-secrets, cloud-specific secrets, after-secrets). However, these partials must exist in the source repository for the build to succeed.Verify that the following partial files exist in the redpanda-connect documentation source:
redpanda-connect:ai-agents:partial$mcp/production-workflows-before-secrets.adocredpanda-connect:ai-agents:partial$mcp/secrets-cloud.adocredpanda-connect:ai-agents:partial$mcp/production-workflows-after-secrets.adocIf these partials do not yet exist, they must be created in the redpanda-connect repository, or the includes must be adjusted to point to existing partials. You can verify this by checking the redpanda-connect-docs repository or by running the documentation build.
217-221: Suggested reading references are appropriate and complete.Cross-references to components, Bloblang guide, and secret management are standard and helpful for readers seeking deeper knowledge.
Separate variable declaration from assignment in validate_mcp_metadata to avoid masking return values and resolve ShellCheck warnings.
Remove Grafana and Datadog export instructions since one-span-per-topic format is incompatible with batch-based platform requirements.
| @@ -0,0 +1,19 @@ | |||
| redpanda: | |||
There was a problem hiding this comment.
does this work? in MCP there must be one component at the root IIRC
There was a problem hiding this comment.
yeah outputs and inputs can have individual processors too
birdayz
left a comment
birdayz
left a comment
There was a problem hiding this comment.
thank you looks very good ! left one other comment.
local-antora-playbook.yml
Outdated
| start_paths: [docs,'*/docs'] | ||
| - url: https://github.com/redpanda-data/rp-connect-docs | ||
| branches: main | ||
| branches: single-source |
| == See also | ||
|
|
||
| * xref:ai-agents:mcp-server/overview.adoc[] | ||
| * https://docs.redpanda.com/redpanda-connect/configuration/unit_testing[Unit Testing Guide^] |
There was a problem hiding this comment.
It’s an internal doc. Doesn’t get published.
There was a problem hiding this comment.
I'll update the other links.
| == Why use a Remote MCP server? | ||
| == Why use an MCP server? |
There was a problem hiding this comment.
is this change correct? page title still says remote
There was a problem hiding this comment.
Yeah just standardizing on the terms. The feature is Remote MCP, but what you create is an MCP server.
There was a problem hiding this comment.
I agree that this heading should use the feature name.
| :description: Create and host a managed MCP server inside your Redpanda Cloud cluster with tools for generating and publishing user event data. | ||
| :description: Learn how to extend AI agents with custom tools that interact with your Redpanda data using the Model Context Protocol (MCP). | ||
|
|
||
| Model Context Protocol (MCP) enables AI assistants like Claude to interact with external systems through custom tools. This quickstart teaches you how to create an MCP server in Redpanda Cloud with tools that generate and publish event data, then connect Claude Code to use those tools through natural language commands. |
There was a problem hiding this comment.
i feel like we should be more explicit that only claude is available at this time. People will probably ask if they can use this with gemini, grok, etc.
There was a problem hiding this comment.
You can use other tools, we just choose to use Claude in the quickstart
Description
Resolves https://redpandadata.atlassian.net/browse/DOC-1846
Review deadline: December 10
This pull request introduces automated testing for Redpanda Cloud MCP server examples, improves documentation and navigation for MCP server management, and removes beta labels.
Automated Testing & Documentation
.github/workflows/test-mcp-examples.yamlworkflow to automatically test MCP example YAML files and the test script on every push and pull request.modules/ai-agents/examples/test-mcp-examples.sh, a Bash script that lints example configs and validates MCP metadata, with color-coded output and summary.modules/ai-agents/examples/testing.adocdocumentation describing automated and manual testing strategies, script usage, and best practices for MCP examples.MCP Server Management Documentation
modules/ai-agents/pages/mcp/remote/admin-guide.adocto overview administrative tasks for Remote MCP servers, and split details into new guides for server management, scaling, and monitoring.modules/ROOT/nav.adocto include new guides:manage-servers.adoc,scale-resources.adoc, andmonitor-activity.adocfor Remote MCP server administration.Minor Documentation & UI Improvements
single-sourcebranch for documentation builds (temporary - do not merge)These changes collectively improve MCP example quality assurance, clarify server management, and keep CI/CD tooling up to date.
Page previews
Checks