Repository navigation
MCP: Launch OAuth and the 2026-07-28 protocol #2408
Description
Launch a Data API MCP endpoint that clients connect to through OAuth sign-in. Support protocol 2026-07-28 and add newer revisions only after testing them. Older protocol versions, session-based connections, and manually supplied AstraCS tokens will no longer work for MCP. Ordinary Data API HTTP authentication remains separate.
The work has three parts. Build the protocol and authentication support, prove that clients can connect, and verify the deployed service before release.
| Part | Work | Completion evidence |
|---|---|---|
| Build the service | #2625 implements the protocol. #2642 adds OAuth authentication and resource discovery. A companion authorization service handles sign-in, consent, registration, and renewal. | Implementation and focused tests for both services. |
| Prove clients can connect | #2626 checks raw HTTP behavior. #2630 covers browser origins. #2633 tests the complete OAuth flow with exact client builds, including IBM Bob. | Passing protocol checks and a recorded client support matrix. |
| Prepare and verify the release | #2635 protects logs. #2643 supplies connection and migration instructions. #2634 verifies the public deployment and rollout plan. | Deployed tests, reviewed documentation, and release approval. |
The launch milestone tracks required work. #2624 records the agreed policy. Each implementation ticket can close on its own evidence. This tracker closes when the client, deployment, documentation, and operations checks also pass.
The companion authorization service still needs a named owner, tracking reference, and contract revision linked here and from #2642 and #2633. Keep sensitive implementation details in approved private records and use a public-safe reference here. Confirm owners for the other unassigned launch tickets during triage.
The independent follow-ups are #2627 readable results, #2628 setup errors, #2629 request cleanup, #2631 update schemas, #2632 command validation, and #2636 tool behavior hints. They enter the launch milestone only when a demonstrated problem blocks required client behavior. #2631 remains under #2604.
Status on October 23, 2026
| Work | Current evidence | Remaining work |
|---|---|---|
| Protocol policy #2624 | The decision is closed and unchanged. | Implementation and release evidence remain separate. |
| Protocol #2625 | PR #2644 merged on October 23 with Quarkiverse MCP Server 2.0.3 and a stateless tools/list test. PR #2659 moves to 2.1.0.Beta1 and accepts only protocol 2026-07-28. | Merge #2659 once a stable 2.1.0 ships. Stop advertising the logging capability, and fix the 500 for a clientInfo without a name and the 200 for malformed JSON. |
| Schemas #2604 and #2631 | PR #2619 merged on October 23 with the clause schemas and contract tests. PR #2651 adds update syntax for #2631. PR #2658 gives every tool argument a description. | Review and merge #2651 and #2658. The rest of the #2604 descriptions and examples still wait on single-leg and filter retrieval. |
| Request cleanup #2629 | PR #2645 closes each command context when a tool call ends. PR #2656 tests overlapping calls and documents tracing support. | Review and merge both, then enable tracing and set baggage limits. |
| Readable results #2627 | PR #2652 returns the full response as readable JSON text. | Review and merge. Check client display in #2633. |
| Setup errors #2628 | PR #2653 handles setup failures at one shared boundary. | Review and merge. |
| Safe logging #2635 | PR #2648 passed 85 focused tests locally. | Review and merge. Verify deployed logging in #2634. |
| Tool behavior #2636 | PR #2649 publishes hints for all 35 tools. | Review and merge. This remains an independent follow-up. |
| Validation #2632 | PR #2655 applies the HTTP command validation to MCP and adds an MCP guide. | Review and merge. |
| OAuth #2642 | Draft PR #2617 contains preparatory bearer-token work. #2654 tracks the complete OAuth flow. | Name the companion service owner, tracking reference and contract revision, then implement and test admission and discovery. |
| Verification #2626, #2630, #2633 and #2634 | The first raw HTTP test merged with #2644. PR #2659 adds 33 protocol tests for #2626. Draft PR #2657 adds the Origin check for #2630. | The protocol tests need CI results. Approved origins, OAuth client and deployed checks are still not recorded as complete. |
| Documentation #2643 | Logging guidance in #2648, the tool behavior guide in #2649 and the MCP guide in #2655 are ready to draft from. | Publish reviewed connection and migration instructions using actual client and deployment evidence. |
The follow-up PRs form one stack and merge in this order. #2651, #2645, #2652, #2653, #2648, #2649, #2655, #2656. Each one targets the branch of the PR below it, so only the bottom PR gets CI. The combined stack passed 381 focused tests locally, which is not a CI result. PRs #2657, #2658 and #2659 target main on their own. PRs #2657 and #2659 both edit application.yaml, so whichever merges second needs a small merge. No release checkbox is complete based on these changes.
Implementation requirements and source references
Deliver an OAuth-only MCP endpoint on protocol 2026-07-28, plus explicitly implemented and qualified newer revisions. Reject older/unknown revisions and old session/initialize flows. AstraCS and Token/token/X-Cassandra-Token must not authenticate MCP. Ordinary Data API HTTP authentication is a separate surface.
Use the launch milestone for release scope and live completion. Native sub-issues preserve ownership/history and native dependencies show ordering. Optional follow-ups stay outside the milestone. The total sub-issue percentage includes follow-ups and is not release readiness.
Delivery map
Stable IDs below correspond to the delivery plan. Changelog IDs M/m/D/S/G/P are case-sensitive. H1–H7 identify the authorization flow and L1–L6 identify release gates.
| Workstream | Implementation or decision | Verification and handoff |
|---|---|---|
| Handshake | #2642: H1 resource metadata, H6 protected calls. Companion authorization-service contract: H2 issuer discovery, H3 registration, H4 authorization, H5 callback issuer, H7 renewal | #2633: full browser/client flow. #2626: raw auth failures. L1 closes only with both sides evidenced |
| Protocol | #2624: agreed contract and G1. #2625: modern wire implementation | #2626: raw conformance. #2630: Origin/CORS. L2 protocol gate |
| Bring to market | #2633: L3 exact client/build matrix. #2643: L5 onboarding and migration | #2634: L4 deployed verification and L6 operations. #2635: credential-safe logging |
No primary client vendor. Qualify conforming clients, including IBM Bob, and publish exact tested builds. An ID token cannot authorize MCP. The removed MCP initialization handshake is distinct from OAuth authorization.
Release completion
- L1: MCP: Add OAuth authentication and discovery #2642 and the companion authorization-service contract have owners, implementation and focused test evidence. MCP: Test OAuth sign-in with supported clients #2633 proves their integration.
- L2: MCP: Agree the supported protocol and authentication policy #2624/MCP: Support the 2026-07-28 protocol without legacy sessions #2625/MCP: Test protocol and OAuth behavior over HTTP #2626/MCP: Reject requests from unapproved browser origins #2630 establish the agreed modern contract and passing packaged conformance.
- L3: MCP: Test OAuth sign-in with supported clients #2633 records actual host/SDK/build and full OAuth results. Test tokens alone do not prove consent or callback handling.
- L4: MCP: Verify the deployed service and prepare rollout #2634 verifies the exact artifact through the public edge, replicas and pod replacement.
- L5: MCP: Publish connection and migration instructions #2643 publishes reviewed onboarding, migration, permission troubleshooting and the qualified client matrix.
- L6: MCP: Protect payloads and OAuth credentials in logs #2635 verifies safe logs. MCP: Verify the deployed service and prepare rollout #2634 records measured promotion/rollback thresholds, owner and runbook. Disable MCP if rollback would restore prohibited access.
Confirm unassigned delivery owners during triage. Closing implementation tickets does not close downstream qualification or deployment gates. Keep environment-specific configuration, private implementation references and operational evidence in approved private records. Public evidence must be redacted.
Complete changelog coverage and immutable source lines
These references use immutable source lines at spec commit 3778656b2e0ba6725035e816fe3085374cbaa736. Required applies to our supported surface. Conditional means we need the behavior only when exposing that feature. No new feature means deliberately leave the optional capability unadvertised.
| Item | Action or disposition | Tracking |
|---|---|---|
| M1 Remove protocol sessions | Required. Stop creating or depending on MCP sessions. | Build #2625; verify #2626 |
| M2 Remove initialization | Required. Require protocolVersion and clientCapabilities in each request _meta. | Build #2625; verify #2626 |
| M3 Implement server discovery | Required. Implement server/discover and advertise only implemented, qualified revisions at or above 2026-07-28, with accurate capabilities and identity. | Build #2625; verify #2626 |
| M4 Use POST subscriptions for change events | Conditional. Do not advertise listChanged or resource subscription capabilities unless supported end to end. | Build #2625; verify #2626 |
| M5 Remove obsolete utility methods | Required. Remove ping, logging/setLevel and roots/list_changed from the modern surface. | Build #2625; verify #2626 |
| M6 Move tasks to an extension | No new feature. Do not advertise or implement tasks for this tools-only launch. | Build #2625; verify #2626 |
| M7 Use multi round trip requests | Conditional. Current tools do not need server-initiated roots, sampling or elicitation. | Build #2625; verify #2626 |
| M8 Tag every successful RPC result | Required. Assert resultType: complete on discovery, tool lists and completed calls, including tool results with isError. | Build #2625; verify #2626 |
| M9 Remove stream redelivery | Required. Do not emit SSE event IDs or resume a stream with Last-Event-ID. | Build #2625; verify #2626 |
| m1 Advertise optional extensions | Required audit. Ensure capability serialization accepts the extensions map. | Build #2625; verify #2626 |
| m2 Propagate trace context | Recommended. Audit framework propagation of traceparent, tracestate and baggage from _meta using the MCP OpenTelemetry conventions. | Build/test #2629 |
| m3 Return tools in stable order | Recommended. Return a deterministic tools/list order, including stable pagination under an unchanged catalog. | Build #2625; verify #2626 |
| m4 Validate standard HTTP headers | Required. Require Mcp-Method on every POST request and Mcp-Name for tools/call, resources/read and prompts/get. | Build #2625; verify #2626 |
| m5 Include cache hints | Required. Include integer ttlMs >= 0 and cacheScope on complete tools/list results and server/discover, which the detailed caching specification also covers. | Build #2625; verify #2626 |
| m6 Correct resource not found errors | Conditional. Audit dependency behavior: an implemented resources/read missing resource must return -32602, not the older -32002. | Build #2625; verify #2626 |
| m7 Validate authorization response issuer | Required auth. The authorization service emits iss on success and error callbacks and advertises support. | Authorization service; verify #2633 |
| m8 Set registration application type | Conditional auth. Prefer pre-registration or Client ID Metadata Documents. | Authorization service; verify #2633 |
| m9 Scope registration credentials to issuer | Required auth. Persist authorization-server-issued registration credentials under the exact issuer. | Authorization service/client contract; verify #2633 |
| m10 Support the current schema model | Required audit. Validate generated schemas as JSON Schema 2020-12 and avoid object-only assumptions for structuredContent. | Build #2625; verify #2626 |
| m11 Remove old elicitation completion | No new feature. Do not advertise URL elicitation for this launch. | Build #2625; verify #2626 |
| m12 Use final protocol error codes | Required. Assert HeaderMismatch -32020, MissingRequiredClientCapability -32021 and UnsupportedProtocolVersion -32022, not earlier draft values. | Build #2625; verify #2626 |
| D1 Avoid deprecated roots sampling and logging | No new feature. These features are deprecated, not yet removed from the entire spec. | Build #2625; verify #2626 |
| D2 Retire the old HTTP plus SSE transport | Required. Expose only the supported Streamable HTTP flow at the MCP endpoint. | Build #2625; verify #2626 |
| D3 Avoid deprecated sampling context values | No new feature. Data API does not need sampling for this release. | Build #2625; verify #2626 |
| D4 Prefer client metadata documents over DCR | Required auth decision. Use established pre-registration where available and support CIMD in the new authorization-server design. | Authorization service; verify #2633 |
| S1 Preserve fractional schema numbers | Required regression. Ensure schema tooling preserves number-valued minimum, maximum and default. | Build #2625; verify #2626 |
| G1 Track feature lifecycle | Process. Record Active, Deprecated and Removed states in the capability inventory. | Contract #2624; publish #2643 |
| P1 Use the SEP contribution process | Process. When an implementation gap requires upstream changes, use the PR-based SEP process with sponsors and labels. | Coordination #2408 |
The detailed caching section also requires cache hints for complete server/discover results, even though the changelog cache bullet lists only the primitive endpoints. The full-changelog comparison link is a reference index, not an additional runtime requirement.
Independently schedulable follow-ups
#2627 readable results, #2628 setup errors, #2629 context/tracing, #2631 update schemas, #2632 validation parity and #2636 behavior hints remain separate. Preserve #2631 under #2604. Promote a follow-up into the launch milestone and add a blocking relationship only if required or promised client behavior fails.
P1: use the upstream PR-based SEP process for specification changes and pin the revision in test evidence. Candidate framework: Quarkiverse MCP Server 2.0.3. Restrict admission and discovery explicitly because it also supports old revisions. Authorization requirements.
This tracker records planned work, not completed runtime qualification.
Authorization-service ownership and readiness
Record the companion authorization-service owner, tracking reference and contract revision before marking authentication complete. Link the reference from #2642 and #2633. Keep sensitive implementation details in approved private records and use a public-safe reference in these tickets.
The contract must identify the deployed issuer and supported metadata mechanism, with implementation and test evidence for registration, authorization, callback handling and renewal. The service must publish at least one supported authorization-server metadata mechanism. The client fallback fixtures in #2633 do not require the service to host every alternative discovery URL.
See the authorization overview and authorization-server discovery.
Activity
[-]Add MCP Support for Data API[/-][+]MCP: Data API support[/+][-]MCP: Data API support[/-][+]MCP: Data API upgrade and follow-up work[/+][-]MCP: Data API upgrade and follow-up work[/-][+]MCP: Deliver OAuth and the 2026-07-28 protocol without legacy clients[/+][-]MCP: Deliver OAuth and the 2026-07-28 protocol without legacy clients[/-][+]MCP: Launch OAuth and the 2026-07-28 protocol[/+]