MCP: Add OAuth authentication and discovery #2642

Tracking issue: #2408. Workstream: Handshake. Launch required.

Requirement IDs: H1 resource discovery, H6 token exchange and protected calls, L1 authentication contract. H2–H5 and H7 are authorization-service integration prerequisites. These IDs are shared with the delivery plan.

Outcome

Implement the OAuth-only MCP protected resource. Implementation is tracked in PR #2669. The earlier preparatory PR #2617 is closed without merging. Preserve authentication for ordinary Data API HTTP endpoints.

Acceptance

• Publish unauthenticated RFC 9728 resource metadata and a 401 Bearer resource_metadata challenge. Also provide well-known discovery. Use a canonical resource identifier and at least one authorization server.

• Require an authorized OAuth access token for protected MCP discovery, listing and execution. Reject ID tokens, manually supplied AstraCS tokens and Token/token/X-Cassandra-Token fallback at the MCP route.

• Validate token authenticity, issuer, audience and expiry before extracting identity or executing tools. Enforce scope and organization/database/operation permissions. Use the agreed JWT/JWKS or opaque-token contract and test rotation, revocation and permission changes.

• Keep identity, the inbound credential and downstream credentials separate. Do not forward the MCP access token to other APIs or embedding/reranking providers.

• Return 401 for missing/invalid credentials and 403 for insufficient scope or permission with the required challenge. Keep offline_access out of resource-required scope challenges. Authorization failures cannot become successful tool results.

• Test forged, expired, wrong-issuer, wrong-audience and wrong-tenant credentials, read-only versus write access, old headers, key rotation and recovery after denial. Metadata must remain reachable without credentials.

• Agree the final subject and permission contract with the authorization service and backend. Test the agreed service-client access JWT through a permitted database operation and a denied organization/database/operation. Preserve existing user-token behavior.

• Record the canonical public resource and issuer URLs, including path prefixes, and which component serves each metadata endpoint. Coordinate public routing and Bearer forwarding checks with MCP: Verify the deployed service and prepare rollout #2634.

Completion evidence

Link the implementation PR, exact artifact/revision and passing focused authorization tests. Record the authorization-service contract revision using a public-safe identifier and redacted configuration evidence. Keep environment-specific configuration and private implementation links in private records.

Close this ticket on its implementation and focused tests. Independent browser/client qualification belongs to #2633, packaged raw HTTP conformance to #2626 and deployed verification to #2634. Those release gates remain open independently.

Sources

Authorization, authorization-server discovery and security considerations. Related changelog IDs m7–m9 and D4 concern the companion authorization-service/client contract, not new resource-server callback endpoints.

Resource discovery checks

Record the public resource identifier and exact metadata URL. Verify unauthenticated GET returns HTTP 200 and application/json, with the expected resource value and a nonempty authorization_servers array of issuer identifiers. Keep the chosen challenge and well-known routes reachable through the deployed edge. The MCP RPC endpoint's GET restriction must leave metadata GET available.

Verify the resource value against the full public identifier, including its path. Keep this OAuth metadata endpoint distinct from protected MCP server/discover. Requiring both server discovery mechanisms remains our interoperability choice. The specification requires at least one.

Link the companion authorization-service owner and contract reference recorded in #2408. Use a public-safe reference if implementation details are private.

See RFC 9728 sections 3.1–3.3 and the MCP discovery requirements.