docs(mcp-servers): rewrite MCP Servers pages for ADP GA#4
Merged
Conversation
✅ Deploy Preview for redpanda-agentic-data-plane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
JakeSCahill
approved these changes
Apr 29, 2026
Greenfield rewrite of the MCP Servers section for the Agentic Data Plane GA (2026-06-15). Bundles three master-plan workflows: #3 Create MCP server (DOC-2111), #9 Register remote/self-hosted MCP (DOC-2117), #10 User-delegated OAuth for MCP (DOC-2118). Changes: * Delete legacy MCP content migrated from cloud-docs (the YAML-pipeline- authoring era): mcp/pages/remote/ (13 pages), mcp/pages/overview.adoc, mcp/pages/local.adoc, mcp/examples/mcp-tools/ (42 YAML files + test-mcp-tools.sh). The cloud-docs equivalents were removed in redpanda-data/cloud-docs#562; this is the same cleanup applied to adp-docs main, where the migration pre-dated #562. * Rewrite mcp/pages/index.adoc as the MCP Servers landing — frames managed + self-managed backends, lists the four ADP-UI top-level areas, points at Cloud Management MCP as a peer. * Stub the 4 must-ship how-tos (create-server, register-remote, user-delegated-oauth, test-tools) + the managed-catalog reference, with full outlines and // TODO: markers for live walkthroughs on adp-production. Auth section uses the new RemoteMCPConfig auth oneof (none / static_key / token_passthrough / service_account_oauth / user_oauth); credential_mode and the CredentialMode enum are gone post- proto-rewrite. * Stub the 5 should-ship managed deep-dives (sql, kafka, slack, jira, openapi). All follow the shared 7-section structure (what the server does -> prereqs -> configure -> test -> auth -> use with agents -> troubleshooting). Live-walkthrough TODOs throughout. * managed-catalog.adoc lists all 27 user-facing managed types from apps/aigw/internal/mcp/managed/mcps/*/register_mcp.go, grouped by ManagedMCPCategory (AI / AWS / Communication / Database / Google / Streaming / Utility), with deep-dive links for the 5 with dedicated pages. * Update modules/ROOT/nav.adoc — replace the legacy Remote/Local subsections with the new flat MCP Servers structure; promote Redpanda Cloud Management MCP Server to a peer top-level section. * Cascade: retarget xrefs in modules/agents/, modules/observability/, and modules/ROOT/pages/adp-overview.adoc that pointed at deleted mcp:remote/* paths. Targets: mcp:remote/overview.adoc -> mcp:index.adoc; mcp:remote/quickstart.adoc + create-tool.adoc -> mcp:create-server.adoc; mcp:remote/register-external.adoc -> mcp:register-remote.adoc; mcp:remote/oauth-user-delegated.adoc -> mcp:user-delegated-oauth.adoc; mcp:remote/monitor-mcp-servers.adoc -> mcp:test-tools.adoc; mcp:remote/{patterns,best-practices,scale,troubleshooting}.adoc and mcp:overview.adoc -> mcp:index.adoc (no direct equivalents). Beta target (2026-05-15) is best-effort; firm commitment is GA on 2026-06-15. // TODO: markers throughout will be resolved through live walkthroughs on adp-production in subsequent commits. Refs: DOC-2111, DOC-2117, DOC-2118 Plan: https://redpandadata.atlassian.net/wiki/spaces/DOC/pages/1869185054 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> # Conflicts: # modules/observability/pages/concepts.adoc # modules/observability/pages/transcripts.adoc
The playbook was pulling from GitHub's main branch instead of the local working directory, causing the build to show old remote/* pages instead of the new managed/* structure. Changed content source from GitHub URL to local directory (.) with HEAD branch so Antora builds from the current branch with all local changes. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Applied comprehensive improvements to all MCP documentation files based on docs team standards review: Style improvements: - Added glossterm macros for key technical terms (tools, resources, prompts, topics, clusters, ACLs) on first mention - Added explicit link text to all xrefs for better accessibility - Fixed heading capitalization to sentence case - Improved introduction paragraphs to lead with value/outcome Content quality: - Rewrote introductions to be more outcome-focused - Standardized xref link text across all files - Improved consistency in terminology usage Testing: - Generated Doc Detective test specifications for create-server.adoc (4 tests, 41 steps validated) - Generated Doc Detective test specifications for test-tools.adoc (7 tests, 41 steps validated) - Both test specs validated successfully Files modified: - modules/mcp/pages/index.adoc - modules/mcp/pages/create-server.adoc - modules/mcp/pages/register-remote.adoc - modules/mcp/pages/test-tools.adoc - modules/mcp/pages/user-delegated-oauth.adoc - modules/mcp/pages/managed-catalog.adoc Files added: - modules/mcp/doc-detective-create-server.json - modules/mcp/doc-detective-test-tools.json These changes address all critical issues identified in the documentation review and prepare the content for GA publication. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
micheleRP
force-pushed
the
adp-mcp-servers-rewrite
branch
from
87df153 to
6be8a41
Compare
Antora rejected aliases pointing at adp-overview.adoc and ai-gateway/what-is-ai-gateway.adoc because cloud-docs main still publishes those pages. Defer both entries with a TODO matching the existing pattern in modules/ROOT/pages/index.adoc, so the build passes until cloud-docs removes the duplicates. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Restore the local-filesystem source (`url: .`, `branches: HEAD`) for adp-docs so the Netlify deploy preview builds the PR branch instead of re-fetching `main`. Other sources stay on GitHub. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Greenfield rewrite of the MCP Servers section for the Agentic Data Plane GA (2026-06-15). Bundles three master-plan workflows: Create MCP server (DOC-2111), #9 Register remote (self-hosted) MCP (DOC-2117), #10 User-delegated OAuth for MCP (DOC-2118). Companion to peer rewrites #2 (AI Gateway) and #3 (Transcripts).
Preview
MCP Servers landing: https://deploy-preview-4--redpanda-agentic-data-plane.netlify.app/redpanda-adp/mcp/
Navigate from the landing page to walk every new and stubbed page (5 must-ship + managed catalog + 5 managed deep-dives). The Cloud Management MCP Server section sits as a peer top-level entry, no longer nested.
What this PR does
mcp/pages/remote/(13 pages),mcp/pages/overview.adoc,mcp/pages/local.adoc,mcp/examples/mcp-tools/(42 YAML files +test-mcp-tools.sh). The cloud-docs equivalents were deleted in redpanda-data/cloud-docs#562; this PR applies the same cleanup to adp-docsmain, where the migration pre-dated #562.mcp/index.adocas the MCP Servers landing — frames managed + self-managed backends, lists the four ADP-UI top-level areas (LLM Providers, MCP Servers, OAuth Providers, My Connections), points at Cloud Management MCP as a peer.create-server.adoc,register-remote.adoc,user-delegated-oauth.adoc,test-tools.adoc,managed-catalog.adoc) with full outlines and// TODO:markers for live walkthroughs. Auth section uses the newRemoteMCPConfig.authoneof (none/static_key/token_passthrough/service_account_oauth/user_oauth);credential_modeand theCredentialModeenum are gone post-proto-rewrite.managed/sql.adoc,managed/kafka.adoc,managed/slack.adoc,managed/jira.adoc,managed/openapi.adoc). Shared 7-section structure (what the server does → prereqs → configure → test → auth → use with agents → troubleshooting); live-walkthrough TODOs throughout.managed-catalog.adoclists all 27 user-facing managed types fromapps/aigw/internal/mcp/managed/mcps/*/register_mcp.go, grouped byManagedMCPCategory(AI / AWS / Communication / Database / Google / Streaming / Utility). Deep-dive links for the 5 with dedicated pages.modules/ROOT/nav.adoc— replaces the legacy Remote/Local subsections with the new flat MCP Servers structure; promotes Redpanda Cloud Management MCP Server to a peer top-level section.modules/agents/,modules/observability/, andmodules/ROOT/pages/adp-overview.adocthat pointed at deletedmcp:remote/*paths. Mapping:mcp:remote/overview.adoc→mcp:index.adoc;mcp:remote/quickstart.adoc+create-tool.adoc→mcp:create-server.adoc;mcp:remote/oauth-user-delegated.adoc→mcp:user-delegated-oauth.adoc;mcp:remote/monitor-mcp-servers.adoc→mcp:test-tools.adoc;mcp:remote/{patterns,best-practices,scale,troubleshooting,manage-servers}.adocandmcp:overview.adoc→mcp:index.adoc(no direct equivalents).Status
Open questions / known issues
// TODO:markers on every concrete sign-in URL, IAM role, OIDC endpoint, feature flag — to be resolved as the standalone ADP product surface ships./redpanda-cloud/ai-agents/mcp/remote/*URLs: not added in this PR; external inbound links will 404 until we addpage-aliases:entries in Weeks 7–8 (or accept the 404s).ManagedMCPType.docs_urldestination: confirm with eng whether the field should point atmanaged-catalog.adoc#anchor-per-typeor at the 5 deep-dive pages where they exist.docs-team-standardsreview.adp-la.adocpartial: present on every new page during the rewrite; remove in Weeks 7–8 per the master-plan GA polish pass.cloud-docs/modules/ai-agents/pages/mcp/{configuration,index,overview,quickstart}.adocplaceholder + nav stub is not touched here. That's a separate workstream.include::ai-agents:partial$adp-la.adoc[](cloud-docs form) instead ofinclude::ROOT:partial$adp-la.adoc[](the correct adp-docs intra-component form). Worth flagging on those PRs' reviews so the same pattern doesn't propagate.Preview pages
Test plan
npm run build && npm run serve) renders the MCP Servers nav with 5 must-ship pages, the catalog, and 5 deep-dive entries; Cloud Management MCP renders as a peer top-level section.adp-production— one server of each auth mode (none,static_key,token_passthrough,service_account_oauth,user_oauth), managed + self-managed.register-remote.adoc; confirmtools/listpopulates.user-delegated-oauth.adoc; confirm My Connections state.test-tools.adoc; capture an error case.adp-production(Weeks 4–6).docs-team-standards:reviewon every new page.adp-la.adocpartial includes at GA (Weeks 7–8).🤖 Generated with Claude Code