docs: sync ADP changes from cloudv2 (2026-06-28)#114
Conversation
…ListOAuthProviders Document the new AIP-160 filter and AIP-132 order_by request fields added to the v1alpha1 ListMCPServers and ListOAuthProviders APIs, so callers can scope and sort these lists server-side. Adds a programmatic List and filter section to create-server.adoc and oauth-providers.adoc, covering the filterable columns, orderable keyset columns, default order, required list permission, and a curl example, mirroring the existing SpendingService programmatic docs. Source: cloudv2 commits 96e2387 (ListMCPServers) and 1295dfa (ListOAuthProviders).
✅ Deploy Preview for redpanda-agentic-data-plane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
[adp-docs PR critic] Verdict: looks accurate. Every field name, enum value, permission, filterable/orderable column, default order, and the Connect URL/auth pattern is correctly grounded in the cloudv2 proto source. Both new sections faithfully mirror the existing Source-accuracy checks (against
Correctness:
Minor:
Policy/positioning: No maturity labels, support statements, or product positioning are touched. The PR itself flags the "should these raw Generated by Claude Code |
|
|
||
| Set `order_by` (maximum 256 characters) to a comma-separated list of fields, each optionally suffixed with ` desc` (ascending by default), for example `created_at desc`. Orderable fields are the keyset columns `name` and `created_at`. An unsupported field returns `InvalidArgument`. Leave `order_by` empty to use the server default (`created_at desc`). The order is encoded into the page token, so keep it stable across a paged walk. | ||
|
|
||
| [,bash] |
There was a problem hiding this comment.
P2 Minor — source-block style inconsistent with the rest of the repo.
What: This new block uses [,bash]. Every other code block in this file (line 151), in oauth-providers.adoc, and in the budgets.adoc SpendingService section this PR explicitly mirrors uses [source,bash].
Why: The two render identically in Asciidoctor, so this is harmless at build time — but it's a needless style split inside a file the PR otherwise keeps aligned with the precedent it cites.
Suggested fix: Change [,bash] to [source,bash].
One-shot prompt: In redpanda-data/adp-docs branch claude/sync-cloudv2-2026-06-28, change the source-block label at modules/connect/pages/create-server.adoc:231 from [,bash] to [source,bash].
|
|
||
| Set `order_by` (maximum 256 characters) to a comma-separated list of fields, each optionally suffixed with ` desc` (ascending by default), for example `display_name` or `created_at desc`. Orderable fields are the keyset columns `name`, `display_name`, and `created_at`. An unsupported field returns `InvalidArgument`. Leave `order_by` empty to use the server default (`created_at desc`). The order is encoded into the page token, so keep it stable across a paged walk. | ||
|
|
||
| [,bash] |
There was a problem hiding this comment.
P2 Minor — source-block style inconsistent with the rest of the repo.
What: This new block uses [,bash]. The existing block in this same file (line 150), the new section in create-server.adoc, and the budgets.adoc precedent all use [source,bash].
Why: Both forms render identically, so it's harmless at build time — but it's a needless style split within the file.
Suggested fix: Change [,bash] to [source,bash].
One-shot prompt: In redpanda-data/adp-docs branch claude/sync-cloudv2-2026-06-28, change the source-block label at modules/connect/pages/oauth-providers.adoc:225 from [,bash] to [source,bash].
| // Source: cloudv2 proto/public/cloud/redpanda/api/adp/v1alpha1/mcp_server.proto (MCPServerService.ListMCPServers, ListMCPServersRequest.Filter.filter + order_by), added in commit 96e2387 (merge #27489). The proto comment lists `display_name` as a filterable column, but the MCPServer resource has no display_name field, so it's omitted here. Orderable columns and the default order come from the storage table options (orderable: name, created_at; default_order_by: created_at desc). Request shapes are proto-accurate but were not exercised against a live cluster. | ||
| == List and filter servers with the API | ||
|
|
||
| To enumerate MCP servers programmatically, call `MCPServerService.ListMCPServers`. Beyond the `name_contains` substring match, the request accepts an AIP-160 `filter` expression and an AIP-132 `order_by`, so you can scope and sort the list on the server (for example, to page through only the managed servers, newest first) instead of filtering the loaded page. |
There was a problem hiding this comment.
P3 Patch — inline example doesn't match the curl below it.
What: This intro says “for example, to page through only the managed servers, newest first,” but the curl example a few lines down filters type = MCP_SERVER_TYPE_REMOTE AND enabled = true.
Why: Minor teaching mismatch — the prose primes the reader for a managed-servers filter the example never demonstrates. (order_by: created_at desc does match “newest first,” so only the type half is off.)
Suggested fix: Align the two — either reword the parenthetical to describe remote + enabled, or switch the curl filter to type = MCP_SERVER_TYPE_MANAGED.
One-shot prompt: In redpanda-data/adp-docs branch claude/sync-cloudv2-2026-06-28, make the create-server.adoc:212 parenthetical and the ListMCPServers curl filter (~line 231) describe the same scenario.
- Use [source,bash] for the ListMCPServers and ListOAuthProviders curl blocks, matching the rest of the repo (Ben P2). - Align the create-server intro with its example: filter the curl on MCP_SERVER_TYPE_MANAGED so it matches "only the managed servers, newest first" (Ben P3). - Note callback_url in the ListOAuthProviders response fields for parity with the full response shape (critic). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
[adp-docs PR critic] Re-review of the new commit Changes verified:
Policy note: The fix commit incorporates two reviewer suggestions (commit message "Ben P2 / P3"). Both are pure style / example-alignment — choice of The rest of the PR is unchanged from my first review and remains accurate against the proto source. Generated by Claude Code |
4 participants
Summary
Syncs a backend (alpha-endpoint) ADP change merged to
cloudv2mainin the last 24 hours: thev1alpha1ListMCPServersandListOAuthProvidersAPIs gained an AIP-160filterexpression and an AIP-132order_by, letting callers scope and sort these lists server-side.Per the ADP docs policy, alpha UI frontend changes are not documented, but backend alpha endpoints are. The matching cloud UI work (server-side Type/Status faceting, the
/agentsStatus filter URL fix) and the internalcn→cnfastperf change are intentionally not documented here.cloudv2 commits documented
96e2387— feat(aigw): server-side AIP-160 filter + order_by for ListMCPServers (merge #27489)filter+order_bytoListMCPServersRequestinproto/public/cloud/redpanda/api/adp/v1alpha1/mcp_server.proto.1295dfa— feat(aigw): server-side AIP-160 filter + order_by for ListOAuthProviders (merge #27491)filter+order_bytoListOAuthProvidersRequestinproto/public/cloud/redpanda/api/adp/v1alpha1/oauth_provider.proto.What changed in the docs
modules/connect/pages/create-server.adoc— new List and filter servers with the API section documentingMCPServerService.ListMCPServers: thefilterobject (name_contains+ AIP-160filter), filterable columns,order_bykeyset columns, default order, thedataplane_adp_mcpserver_listpermission, and a curl example.modules/connect/pages/oauth-providers.adoc— new List and filter providers with the API section documentingOAuthProviderService.ListOAuthProvidersalong the same lines (dataplane_aigateway_oauthprovider_listpermission).Both sections mirror the existing
SpendingServiceprogrammatic docs incontrol/budgets.adoc, including the standard "proto-accurate but not exercised against a live cluster" provenance note (in source comments). Every field name, enum value, permission, orderable/filterable column, and default order is grounded in the proto source.Accuracy notes
ListMCPServersproto comment listsdisplay_nameas a filterable column, but theMCPServerresource has nodisplay_namefield. I omitted it from the MCP docs and recorded why in a source comment. (The OAuthdisplay_namecolumn is real and is documented.)name/created_at; OAuth providers onname/display_name/created_at; both default tocreated_at desc.For human review (please confirm)
filter/order_byfields primarily back the cloud UI faceting; therpk ai mcp list/rpk ai oauth listCLI still exposes only--filter-name. This PR documents the rawv1alpha1Connect list API as a programmatic surface (following thebudgets.adocprecedent). If you'd prefer not to surface these list endpoints as a sanctioned user-facing workflow yet, drop these sections — that's a positioning call, not a source-accuracy one.Reviewers
Added @malinskibeniamin (author of both source commits) as an optional reviewer for a source-accuracy courtesy check — their approval is not blocking. No other authors to add;
micheleRPis skipped as the PR author.Preview
Deploy preview (live once Netlify finishes the build): https://deploy-preview-114--redpanda-agentic-data-plane.netlify.app/agentic-data-plane/connect/oauth-providers/