Improve MCP devex #478
Improve MCP devex #478
Conversation
- Add new pages: best-practices, concepts, reference, tool-patterns, troubleshooting - Remove deprecated pages: developer-guide, pipeline-patterns - Improve MCP overview with deployment comparison table - Update quickstart and admin-guide for clarity - Align structure with rp-connect-docs for single-sourcing
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis PR restructures and expands MCP (Model Context Protocol) documentation while updating build configuration and terminology. The playbook branch for rp-connect-docs changes from Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
modules/get-started/pages/whats-new-cloud.adoc (1)
99-107: Fix broken migration guide cross-reference link.The migration guide file exists at
modules/develop/pages/connect/guides/migrate-unified-redpanda-migrator.adoc, but the xref path on line 102 is incorrect. The linkxref:guides:migration/migrate-unified-redpanda-migrator.adoc[]references amigration/path that doesn't match the actual file location inconnect/guides/. Correct the xref to properly resolve to the existing migration guide.
🤖 Fix all issues with AI Agents
In @modules/ai-agents/pages/mcp/remote/admin-guide.adoc:
- Line 61: Add the missing anchor [[remote-mcp-billing-metrics]] into the
billing document (billing.adoc) at the section that describes MCP billing
metrics so the xref target exists; update the heading or immediately preceding
paragraph for MCP billing metrics to include the anchor label exactly as
[[remote-mcp-billing-metrics]] so links from remote/admin-guide.adoc and
scale-resources.adoc resolve.
🧹 Nitpick comments (1)
modules/ai-agents/examples/weather_service.yaml (1)
23-33: Well-structured mutation with comprehensive weather fields.The expanded mutation effectively demonstrates field mapping from the wttr.in API response. The field paths are correct, and using
.number()for numeric conversions is appropriate.Optional: Consider demonstrating defensive field access patterns
For additional robustness in production scenarios, the documentation might mention using optional access patterns to handle missing fields gracefully:
- mutation: | root = { "city": @city, "temperature_c": this.current_condition.0.temp_C.number().catch(null), "temperature_f": this.current_condition.0.temp_F.number().catch(null), "feels_like_c": this.current_condition.0.FeelsLikeC.number().catch(null), "humidity": this.current_condition.0.humidity.number().catch(null), "description": this.current_condition.0.weatherDesc.0.value.catch("Unknown"), "wind_speed_kmh": this.current_condition.0.windspeedKmph.number().catch(null), "timestamp": now().format_timestamp("2006-01-02T15:04:05Z07:00") }This pattern could be valuable if the documentation also covers error resilience strategies.
📜 Review details
Configuration used: Organization 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 (25)
local-antora-playbook.ymlmodules/ROOT/nav.adocmodules/ai-agents/examples/testing.adocmodules/ai-agents/examples/weather_service.yamlmodules/ai-agents/pages/index.adocmodules/ai-agents/pages/mcp/local/configuration.adocmodules/ai-agents/pages/mcp/local/overview.adocmodules/ai-agents/pages/mcp/local/quickstart.adocmodules/ai-agents/pages/mcp/overview.adocmodules/ai-agents/pages/mcp/remote/admin-guide.adocmodules/ai-agents/pages/mcp/remote/best-practices.adocmodules/ai-agents/pages/mcp/remote/concepts.adocmodules/ai-agents/pages/mcp/remote/developer-guide.adocmodules/ai-agents/pages/mcp/remote/manage-servers.adocmodules/ai-agents/pages/mcp/remote/monitor-activity.adocmodules/ai-agents/pages/mcp/remote/overview.adocmodules/ai-agents/pages/mcp/remote/pipeline-patterns.adocmodules/ai-agents/pages/mcp/remote/quickstart.adocmodules/ai-agents/pages/mcp/remote/reference.adocmodules/ai-agents/pages/mcp/remote/scale-resources.adocmodules/ai-agents/pages/mcp/remote/tool-patterns.adocmodules/ai-agents/pages/mcp/remote/troubleshooting.adocmodules/develop/pages/connect/configuration/resource-management.adocmodules/develop/pages/connect/configuration/secret-management.adocmodules/get-started/pages/whats-new-cloud.adoc
💤 Files with no reviewable changes (2)
- modules/ai-agents/pages/mcp/remote/developer-guide.adoc
- modules/ai-agents/pages/mcp/remote/pipeline-patterns.adoc
🧰 Additional context used
🧠 Learnings (6)
📓 Common learnings
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.
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:41:57.162Z
Learnt from: micheleRP
Repo: redpanda-data/cloud-docs PR: 267
File: modules/manage/pages/maintenance.adoc:91-92
Timestamp: 2025-04-25T01:41:57.162Z
Learning: The notification timeline for Redpanda Cloud deprecations has been deliberately removed from the documentation, even though the PR summary mentioned a 180-day advance notice period.
Applied to files:
modules/get-started/pages/whats-new-cloud.adoc
📚 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-15T02:29:34.901Z
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.
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/index.adoc
⏰ 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 (60)
modules/ai-agents/examples/weather_service.yaml (2)
3-3: LGTM! Documentation callout annotations are properly structured.The numbered callout markers (<1> through <6>) follow standard Asciidoc conventions for referencing code sections in documentation. These annotations enhance the example's educational value by allowing the accompanying documentation to reference specific steps.
Also applies to: 15-15, 17-17, 38-38, 51-51
51-60: LGTM! MCP metadata is well-structured and descriptive.The meta section properly defines the MCP tool configuration with:
- Clear, user-facing description for AI agents
- Well-documented city parameter with type, description, and required status
- Appropriate tags for categorization
This follows MCP best practices and provides clear guidance for agent integration.
local-antora-playbook.yml (1)
26-26: LGTM! Temporary playbook configuration for preview build.The branch change to
improve-mcp-devexand thesnapshot: trueflag are appropriate for previewing cross-repository documentation changes during development.Based on learnings, this playbook configuration will be reverted to
mainbefore merging, which is the standard pattern for single-sourced content across repositories.Also applies to: 30-30
modules/develop/pages/connect/configuration/resource-management.adoc (1)
128-128: LGTM! Terminology update aligns with Cloud Console rebranding.The update from "Cloud UI" to "Cloud Console" is consistent with the broader terminology standardization across the documentation.
Also applies to: 155-155
modules/get-started/pages/whats-new-cloud.adoc (1)
74-74: LGTM! Updated navigation aligns with restructured MCP documentation.The change from a single developer guide link to separate quickstart and best practices links reflects the improved navigation structure described in the PR objectives.
modules/ai-agents/pages/mcp/remote/scale-resources.adoc (3)
3-9: Excellent addition of structured metadata.The page metadata (topic type, personas, and learning objectives) improves content discoverability and helps readers understand what they'll accomplish from this page.
21-37: LGTM! Enhanced resource sizing guidance.The expanded resource size descriptions (XSmall through XLarge) with use-case guidance help users make informed decisions about resource allocation. The terminology update to "Cloud Console" maintains consistency with the broader documentation changes.
40-63: Valuable addition of Data Plane API instructions.The API section provides programmatic access for users who prefer automation or CI/CD integration. The example is clear and includes proper authentication guidance.
modules/ai-agents/examples/testing.adoc (2)
70-72: LGTM! Improved formatting enhances readability.The definition list syntax (
name:: description) is more semantic and easier to scan than the previous bulleted list format.
239-294: Excellent addition of contributor guidance.The "Adding new examples" section provides clear, step-by-step instructions for contributors, including file creation, metadata requirements, linting, testing, and commit guidelines. This will significantly improve the quality and consistency of new MCP tool examples.
modules/ai-agents/pages/mcp/remote/tool-patterns.adoc (2)
1-13: Well-structured documentation page with clear organization and comprehensive pattern catalog.The use of include directives enables single-sourcing of content, which is appropriately leveraged here across both local examples and cross-component partials. The frontmatter metadata (personas, learning objectives, page-topic-type) is well-defined for documentation discovery, and the pattern selection guide effectively guides readers to relevant sections. The cross-references to related pages (quickstart, best-practices, concepts) are properly formatted.
296-301: Verify cross-component partials exist in the rp-connect-docs improve-mcp-devex branch.Lines 296, 299, 301 include partials from the
redpanda-connectcomponent. Antora enables collecting content from multiple Git repositories into a single documentation site. Based on learnings, these includes should resolve during the playbook build when rp-connect-docs is linked via local-antora-playbook.yml. Confirm that the corresponding improve-mcp-devex branch PR in rp-connect-docs contains these partial files.modules/develop/pages/connect/configuration/secret-management.adoc (1)
18-64: Well-executed updates to Cloud Console terminology and expanded API guidance.The tab labels have been consistently updated to "Cloud Console" and the Data Plane API sections now include detailed curl examples with explicit field descriptions. The Base64 encoding requirement is clearly stated, and the cross-link to <<add-a-secret-to-a-data-pipeline,add the secret to your data pipeline>> (lines 30, 61) provides good user journey guidance. These additions improve clarity and completeness for users preferring programmatic secret management.
modules/ai-agents/pages/mcp/remote/monitor-activity.adoc (3)
1-21: Clear refocusing toward practical execution log consumption with improved learning objectives and guidance.The updated metadata (personas, learning objectives, page-topic-type: how-to) is well-defined for this guide format. The introduction now emphasizes the execution log as the primary monitoring mechanism, and the cross-references to xref:ai-agents:mcp/remote/concepts.adoc#execution-log[Execution log and observability] and xref:ai-agents:mcp/remote/reference.adoc#trace-data-structure[Trace data structure] provide appropriate conceptual context. The concrete learning objectives (consume traces, track invocations, measure performance, debug failures) align well with the guide's scope.
62-95: Practical trace consumption guidance with concrete examples.The sections for tracking tool invocations (filtering by
instrumentationScope.name), measuring performance (duration calculation with formula and example), and debugging failures (status.code 2 reference) provide actionable guidance. The example on line 82 showing duration calculation from Unix nanosecond timestamps is particularly helpful for users implementing monitoring solutions.
111-115: All cross-references are properly defined. The anchors[[execution-log]](concepts.adoc, line 47) and[[trace-data-structure]](reference.adoc, line 80) exist as expected, and manage-servers.adoc is present with proper structure. The xref links in lines 113-115 are valid.modules/ai-agents/pages/mcp/local/configuration.adoc (1)
4-10: Metadata additions are well-structured and align with content.The learning objectives directly map to the main sections (manual setup, delete operations, troubleshooting), and the personas are appropriate for this configuration guide.
modules/ai-agents/pages/mcp/remote/reference.adoc (4)
7-23: Learning objectives and checkpoint structure are well-organized.The use of attribute references in checkbox lists is a clear way to tie learning objectives to the page content. The six objectives align with the reference sections provided.
87-200: Trace data structure documentation is clear and comprehensive.The example span, field reference table, and MCP-specific values are well-organized and provide actionable reference material for developers integrating trace data.
28-28: The include directives follow the documented cross-repository single-sourcing pattern used in Redpanda documentation. External component references likeredpanda-connect:ai-agents:partial$are configured via the Antora playbook and resolve correctly during the build process. These partials may exist in linked PRs in the redpanda-connect repository and will be available upon merge. No action needed.Likely an incorrect or invalid review comment.
52-52: Fix broken xref to tool-patterns.adocLine 52 references
xref:ai-agents:mcp/remote/tool-patterns.adoc#secrets[MCP patterns], but tool-patterns.adoc does not contain a[[secrets]]anchor. The file covers patterns like consuming/publishing topics, stream processing, and AI/LLM integration, but no secrets management section. Either add a secrets section to tool-patterns.adoc or update the xref to point to best-practices.adoc#secrets instead.The other xrefs on lines 78, 83, and 206-210 are valid (best-practices.adoc#secrets, best-practices.adoc#tags, and concepts.adoc#execution-log all exist).
⛔ Skipped due to learnings
Learnt from: micheleRP Repo: redpanda-data/cloud-docs PR: 278 File: modules/manage/pages/cluster-maintenance/config-cluster.adoc:75-75 Timestamp: 2025-04-29T18:43:42.666Z Learning: In AsciiDoc documentation used by Redpanda, empty cross-references (xrefs) without link text (like `xref:manage:rpk/intro-to-rpk.adoc[]`) automatically use the target page's title as the link text.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.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.modules/ai-agents/pages/mcp/remote/admin-guide.adoc (1)
3-9: Metadata additions are appropriate for an administrative overview.The learning objectives align with the operational focus (server management, API usage, lifecycle stages), and the personas are well-suited for administrators and platform engineers.
modules/ai-agents/pages/mcp/remote/manage-servers.adoc (3)
3-9: Metadata additions are appropriate and well-structured.The page now includes descriptive metadata with clear personas (platform engineers, AI developers) and measurable learning objectives aligned with the operational focus. The reader journey comment ("I operate and maintain") sets appropriate context.
23-23: Cloud Console terminology consistently applied across all UI sections.The terminology has been updated from "Cloud UI" to "Cloud Console" across the Edit, Stop, Start, and Delete operation sections, maintaining consistency with the broader documentation updates in this PR.
Also applies to: 26-26, 69-69, 101-101, 132-132
161-161: Cross-reference to best-practices aligns with new documentation structure.The reference now points to the new best-practices page (replacing the deprecated developer-guide), which is consistent with the PR's restructuring of Remote MCP guidance into focused topic areas.
modules/ai-agents/pages/mcp/remote/best-practices.adoc (4)
1-12: Metadata is well-structured with clear learning objectives and appropriate personas.The page metadata clearly defines:
- Learning objectives (5): Actionable and progressively build from evaluation to application
- Personas (3): Appropriately inclusive of developers, data engineers, and platform architects
- Reader journey: "I want to do this well" sets clear intent for audience seeking best practices
The use of the
page-env-cloud: trueattribute and conditional:env-cloud:variables (lines 64, 124) shows good preparation for content management across environments.
134-137: No action needed. All four referenced MCP pages are included in this PR at the expected locations:concepts.adoc,tool-patterns.adoc,reference.adoc, andtroubleshooting.adocexist inmodules/ai-agents/pages/mcp/remote/. The xref links in the "Next steps" section are valid.Likely an incorrect or invalid review comment.
32-32: The include directive is correct. Theweather_service.yamlfile exists atmodules/ai-agents/examples/weather_service.yaml, and the include syntaxinclude::ai-agents:example$weather_service.yaml[]properly targets the example file within the ai-agents module using valid Antora syntax.
44-44: Remove this comment — the Antora playbook is already correctly linked.The
local-antora-playbook.ymlalready referencesrp-connect-docson theimprove-mcp-devexbranch, which is exactly what's needed for these includes to resolve during the Antora build. No verification or changes are required. Additionally, the file contains 6 partial includes, not 7 as stated in the comment.Likely an incorrect or invalid review comment.
modules/ROOT/nav.adoc (1)
81-85: All referenced MCP topic pages exist in the repository. No action needed.
modules/ai-agents/pages/mcp/remote/concepts.adoc✓modules/ai-agents/pages/mcp/remote/best-practices.adoc✓modules/ai-agents/pages/mcp/remote/tool-patterns.adoc✓modules/ai-agents/pages/mcp/remote/reference.adoc✓modules/ai-agents/pages/mcp/remote/troubleshooting.adoc✓Likely an incorrect or invalid review comment.
modules/ai-agents/pages/mcp/local/quickstart.adoc (3)
4-10: Well-structured metadata additions support content organization.The new page-topic-type, personas, learning objectives, and reader journey comments follow Redpanda documentation conventions and accurately reflect the target audience and learning outcomes. These metadata enhancements align well with the broader MCP restructuring.
24-52: Clear procedural structure with good explanatory context.The three-step setup flow (verify version, authenticate, install) is well-sequenced and each step includes helpful context about what happens after the command executes. The explanatory text builds user confidence in security (e.g., token handling explanation) without overwhelming detail.
62-72: Appropriate guardrail callout and natural next learning steps.The NOTE about delete operations being opt-in is important for user safety and appropriately emphasized. The Next steps section offers a logical progression to advanced configuration without overwhelming the quickstart scope.
modules/ai-agents/pages/mcp/local/overview.adoc (3)
4-10: Personas and objectives appropriately scaled for overview context.The broader persona set (including absolute_beginner) and conceptual learning objectives distinguish this overview from the quickstart, supporting the intended audience breadth. The metadata additions are consistent with file 1 and align with PR restructuring.
21-56: Comprehensive overview content with important security transparency.The progression from capabilities through use cases to security considerations provides readers with complete context. The security section appropriately emphasizes that MCP lacks per-server auditing and access control, which is important risk information for users evaluating the option.
59-68: Well-organized learning paths with clear resource sequencing.The distinction between Next steps (core progression) and Suggested reading (supplementary resources) is clear, and the links are appropriately ordered: quickstart for hands-on learners, configuration for advanced use cases, and external documentation for broader reference material.
modules/ai-agents/pages/index.adoc (1)
1-14: Clean index presentation with proper definition list formatting.The restructured definition list separates the option labels from descriptions for better visual clarity, and the badge macro correctly marks the local MCP as beta. The content concisely contrasts local (quick, built-in) versus remote (custom, team-focused) options to guide users toward the right choice.
modules/ai-agents/pages/mcp/remote/troubleshooting.adoc (3)
21-21: Verify the#debugginganchor exists in best-practices.adoc.The cross-reference to
best-practices.adoc#debuggingdepends on a specific anchor that needs to exist on the best-practices page. Ensure this anchor is present when best-practices.adoc is created.
26-26: External partial includes depend on redpanda-connect repo changes.The three include directives reference partials from the
redpanda-connectrepository:include::redpanda-connect:ai-agents:partial$mcp/troubleshooting-lint.adoc[] include::redpanda-connect:ai-agents:partial$mcp/troubleshooting-runtime.adoc[] include::redpanda-connect:ai-agents:partial$mcp/troubleshooting-connection.adoc[]These partials must exist in the rp-connect-docs repository on the
improve-mcp-devexbranch (as referenced in the temporary playbook configuration). Based on the retrieved learnings, this pattern is standard for cross-repo single-sourcing during preview builds, and the playbook is reverted tomainbefore merging. Verify that the corresponding PRs in rp-connect-docs contain these partial files.Also applies to: 30-30, 34-34
1-44: Well-structured troubleshooting page with clear metadata.The page follows the documentation structure well with appropriate metadata (personas, learning objectives, page-topic-type), a helpful introduction that maps learning objectives to actionable items, and a logical flow through common issue categories. The TIP callout guiding readers to best practices is good UX.
modules/ai-agents/pages/mcp/overview.adoc (4)
29-29: Verify the badge syntax and{page-beta-text}attribute.The badge macro references
{page-beta-text}which should be an AsciiDoc attribute. Ensure this attribute is defined in a parent or global context (likely in the antora.yml or a common header file) so the badge renders correctly with the intended tooltip text.
88-89: Verify cross-references to both quickstart pages.Both
xref:ai-agents:mcp/local/quickstart.adoc[]andxref:ai-agents:mcp/remote/quickstart.adoc[]need to exist or be created as part of this PR. The remote quickstart is being updated; ensure the local quickstart page is also part of the MCP restructuring.
93-93: Verify cross-repo reference to home module.The cross-reference
xref:home:ROOT:mcp-setup.adoc[]points to thehomemodule, which may be in a different repository. Ensure this reference resolves correctly with the configured Antora playbook.
1-93: Excellent restructuring of MCP overview with clear user-centric guidance.The rewrite significantly improves the overview page:
- Clear mental model: Introduces MCP and explains its value before presenting options
- Comparison table: The Local vs. Remote comparison is comprehensive and decision-enabling, covering purpose, infrastructure, ownership, access, and best-use scenarios
- User-goal orientation: The "Which should I use?" section provides specific decision criteria that map to real workflows
- Appropriate personas: Covers absolute beginners through experienced developers
- Logical flow: Progresses from concept → decision framework → action (get started)
The metadata, learning objectives, and reader-journey comments are consistent with the documentation restructuring goals.
modules/ai-agents/pages/mcp/remote/concepts.adoc (5)
27-27: External partial includes for core concept sections.Five include directives reference partials from the
redpanda-connectrepository:include::redpanda-connect:ai-agents:partial$mcp/key-terms.adoc[] include::redpanda-connect:ai-agents:partial$mcp/mcp-tools-concept.adoc[] include::redpanda-connect:ai-agents:partial$mcp/component-mapping.adoc[] include::redpanda-connect:ai-agents:partial$mcp/execution-model.adoc[] include::redpanda-connect:ai-agents:partial$mcp/component-selection.adoc[]These partials (which handle the foundational concept explanation, component mapping, and selection logic) must exist in the rp-connect-docs repository on the
improve-mcp-devexbranch. Per the retrieved learnings, this is standard for single-sourced content during preview builds. Verify these partials are available in the corresponding PR.Also applies to: 33-33, 36-36, 39-39, 45-45
171-171: Verify anchor in reference.adoc and monitor-activity.adoc cross-reference.Line 171 contains two cross-references:
xref:ai-agents:mcp/remote/reference.adoc#trace-data-structure— The#trace-data-structureanchor must exist on the reference.adoc page (which is new in this PR).xref:ai-agents:mcp/remote/monitor-activity.adoc[]— Verify this page exists and is configured correctly.
47-152: Comprehensive execution log and observability content.The "Execution log and observability" section provides strong technical depth:
- Clear explanation of traces, spans, and hierarchical relationships
- Detailed trace structure with well-formatted JSON examples
- Practical guidance on trace attributes (traceId, spanId, name, status.code)
- Parent-child span relationships clearly explained with examples
- Error event handling and debugging guidance
- Important distinction between traces (observability) and audit logs (compliance)
- Proper warnings about sensitive data in traces and ACL recommendations
The content is well-organized, technically accurate, and serves its purpose as a concepts page. The progression from trace fundamentals to practical examples to distinguishing use cases is logical and helpful.
1-12: Solid metadata and learning objectives structure.The page header includes:
- Appropriate page-aliases for backward compatibility (redirects from
understanding-mcp-tools.adoc)- Clear page-topic-type as
concepts- Targeted personas (ai_agent_developer, streaming_platform_developer)
- Five well-defined learning objectives that guide readers through key concepts
The metadata aligns with the documentation restructuring goals and supports discoverability and reader guidance.
1-179: Comprehensive concepts page introducing MCP tools and observability.This page successfully achieves its learning objectives by:
- Establishing terminology and mental models (via included partials)
- Explaining component mapping and execution (via included partials)
- Providing clear guidance on component selection (via included partials)
- Offering deep technical insights into observability via OpenTelemetry traces
- Distinguishing traces from audit logs to clarify proper use cases
- Directing readers to next steps in their learning journey
The mix of single-sourced content (partials from rp-connect-docs) and original content (execution log details) is well-balanced. The JSON examples are concrete and helpful. Cross-references support navigation to related pages.
modules/ai-agents/pages/mcp/remote/overview.adoc (6)
3-9: Metadata and learning objectives structure is sound.The addition of page-topic-type, personas, and learning objectives creates clear guidance for readers and aligns with the PR's navigation restructuring. The objectives are concrete and measurable.
11-17: Learning objectives checklist effectively scaffolds reader expectations.The pattern of using learning objective attributes with checkbox syntax helps readers track their progress and understand the page's value before diving in.
19-51: Content sections are well-organized and accessible.The restructured "What is MCP?" and "Who is this for?" sections use plain language and benefit-focused framing. The use-cases table effectively supports readers in evaluating relevance to their context.
54-54: Verify cross-repository include directives resolve correctly.Lines 54, 93, and 96 include partials from
redpanda-connect:ai-agents:partial$mcp/*. Per your learnings on single-sourced content across repositories, these will resolve via the local-antora-playbook.yml pointing to the improve-mcp-devex branch. Confirm that:
- The rp-connect-docs repository has the improve-mcp-devex branch with these partials:
mcp/use-cases-table.adoc(line 54)mcp/customer-analytics-example.adoc(line 93)mcp/specification-support.adoc(line 96)- The local-antora-playbook.yml playbook is configured with the correct branch reference and will be reverted to
mainbefore merge.Also applies to: 93-93, 96-96
56-90: "How it works" flow and weather example are clear and actionable.The five-step process is concrete and reader-friendly. The YAML example effectively demonstrates a minimal viable tool with proper metadata structure, property definitions, and the required/optional field pattern. The inline labels aid comprehension.
98-110: Verify all referenced documentation pages are present in this PR.The "Next steps" section cross-references five new modular pages (concepts, best-practices, tool-patterns, reference) that replace the previous monolithic Developer Guide. Confirm that the following files are included in this PR and contain expected content:
modules/ai-agents/pages/mcp/remote/concepts.adocmodules/ai-agents/pages/mcp/remote/best-practices.adocmodules/ai-agents/pages/mcp/remote/tool-patterns.adocmodules/ai-agents/pages/mcp/remote/reference.adocPer the PR summary, these should contain redistributed content from the deleted developer-guide.adoc.
modules/ai-agents/pages/mcp/remote/quickstart.adoc (5)
3-10: Metadata and learning objectives are well-aligned with the tutorial format.The page-topic-type (tutorial), personas, and reader journey clearly communicate intent. The four learning objectives progress logically from server creation through tool invocation, supporting hands-on learning.
12-23: Introduction effectively sets expectations and provides context.The outcome-focused opening ("you'll create two tools, then ask Claude Code...") immediately communicates value. The TIP directing readers to concepts.adoc for component background is well-placed and helps less-experienced readers avoid confusion.
181-189: Cloud Console terminology update is appropriate.The change from "Cloud UI" to "Cloud Console" aligns with the PR's unified terminology goal. The tab-based structure (Cloud Console vs Data Plane API) provides both UI and programmatic paths for users.
Confirm that the "Cloud UI" → "Cloud Console" terminology update is applied consistently across all MCP documentation pages in this PR.
384-392: Consolidated troubleshooting approach is efficient and user-friendly.The abbreviated troubleshooting section (three common issues) with a reference to the dedicated troubleshooting.adoc follows a progressive disclosure pattern. This avoids bloating the quickstart while providing immediate help for common problems. The issues selected (startup, connection, topic existence) address the most likely pain points.
394-403: Next steps progression guides readers to appropriate follow-up resources.The reorganized "Next steps" section chains cross-references in a logical progression: deepen understanding (best-practices, concepts) → explore patterns (tool-patterns) → operate (admin-guide) → reference (reference) → troubleshoot (troubleshooting). Descriptors help readers self-direct efficiently.
Verify that
admin-guide.adocand all other referenced pages in the "Next steps" section exist in this PR. Per the PR summary, the new modular pages (best-practices, concepts, reference, tool-patterns, troubleshooting) should replace the previous developer-guide structure.
- Restructure test-mcp-examples.sh to match rp-connect-docs test-all.sh style with sections, color output, and summary table - Add Cloud secrets format validation (Section 3) - Fix redpanda_output_with_processors.yaml: add label, MCP metadata, use secrets format for credentials - Fix best-practices.adoc: reorder sections to match rp-connect-docs, remove debugging section (moved to troubleshooting) - Fix monitor-activity.adoc: update broken xrefs to deleted reference.adoc - Fix troubleshooting.adoc: add debugging techniques section
- Add create-tool.adoc for step-by-step tool creation guide - Delete reference.adoc (content moved to create-tool.adoc and concepts.adoc) - Update nav.adoc to reflect new page structure - Update concepts.adoc, overview.adoc, quickstart.adoc with consistent cross-references and learning objectives - Update tool-patterns.adoc topic type to cookbook
…cloud-docs into improve-mcp-devex
…cloud-docs into improve-mcp-devex
| # Redpanda Cloud Documentation Personas | ||
| # | ||
| # These personas represent the target audience for Redpanda Cloud documentation. | ||
| # Use these when assigning :personas: attributes to documentation pages. |
There was a problem hiding this comment.
Did you have it go through the entire cloud-docs repo to generate these personas, or just the pages in this PR?
There was a problem hiding this comment.
The entire repo.
| :learning-objective-1: Consume traces from the execution log | ||
| :learning-objective-2: Track which tools are being invoked | ||
| :learning-objective-3: Measure tool execution performance | ||
| :learning-objective-4: Debug tool failures using trace data |
| @@ -0,0 +1,47 @@ | |||
| = Remote MCP Server Troubleshooting | |||
There was a problem hiding this comment.
| = Remote MCP Server Troubleshooting | |
| = Troubleshoot Remote MCP Servers |
to have titles consistent with the similar RPCN titles
| . `redpanda_output`: Publishes generated events to a Redpanda topic | ||
|
|
||
| Once connected, you can ask Claude in natural language to "generate 10 events and publish them to Redpanda," and Claude will automatically call your tools to complete the task. | ||
| TIP: For background on how MCP tools work and when to use each component type, see xref:ai-agents:mcp/remote/concepts.adoc[]. |
There was a problem hiding this comment.
@JakeSCahill check out how the prereqs include closing periods but the learning objectives above it do not. We should decide on a standard throughout: https://deploy-preview-478--rp-cloud.netlify.app/redpanda-cloud/ai-agents/mcp/remote/quickstart/
| @@ -1,51 +1,83 @@ | |||
| = About Remote MCP Servers for Redpanda Cloud | |||
There was a problem hiding this comment.
Since we're updating the Remote MCP with the new learning objectives, we should probably also add them to the Local MCP pages. Also getting Admin guide pages looking consistent
…cloud-docs into improve-mcp-devex
Co-authored-by: Michele Cyran <[email protected]>
Co-authored-by: Michele Cyran <[email protected]>
…cloud-docs into improve-mcp-devex
Description
This pull request makes significant improvements to the AI Agents documentation for Redpanda Cloud, focusing on clarifying the differences between local and remote MCP servers, enhancing navigation, and adding structured learning objectives and personas to key pages. It also improves example clarity and updates references to better guide users through the documentation.
Documentation structure and navigation:
Content clarity and learning objectives:
Example and formatting improvements:
These changes collectively make the documentation more user-friendly, easier to navigate, and more effective for both beginners and advanced users.
References:
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16]
Page previews
Checks