[erichare]

What this PR does:

Adds opt-in JWT Bearer authentication and OAuth protected-resource discovery for MCP. OAuth mode rejects legacy MCP credentials and preserves ordinary REST authentication. It validates SmallRye's resolved issuer, key, and resource audience, and passes the encoded token to command execution. A deployment with one public host per database sets stargate.mcp.auth.public-host-suffix, and the metadata, the 401 challenge, and the required aud then come from each request's host. Tokens are accepted from the Authorization header only. OAuth stays disabled by default. Includes a reusable smoke test for discovery, the catalog, and permitted and denied database reads with an issued token.

Which issue(s) this PR fixes:

Refs #2642 and #2643.

Verification

524 focused tests passed with 0 failures, 0 errors, and 0 skips at 4d15d0c0e. That run used JDK 25 with the format check skipped, because the pinned formatter does not run on JDK 25, so CI is the first format check of this commit. With the audience comparison disabled, 5 of the new host-suffix tests failed. The smoke script's 10 unit tests pass, and git diff --check is clean. The packaged MCP suite, the live smoke test, and the local PKCE fixture passed before the rebase onto #2659 and were not rerun. Production Astra authorization, generic MCP-client login, and a token issuer that sets a per-database aud remain unverified. CI runs the unit and DSE/HCD integration suites on this push.

./mvnw -B -ntp test -DskipITs -Dfmt.skip=true -Dxml-format.skip=true -Dsurefire.failIfNoSpecifiedTests=false -Dquarkus.http.test-port=19087 '-Dtest=McpClauseSchemaContractTest,McpCommandValidationTest,McpCustomPathLoggingTest,McpDiagnosticLoggingTest,McpEndpointConfigSourceFactoryTest,McpLoggingFilterTest,McpLoggingTest,McpOpenApiSchemaAdapterTest,McpProtocolTest,McpRequestContextProviderTest,McpResourceTest,McpSchemaCustomizerTest,McpSetupErrorsTest,McpToolAnnotationsTest,McpUpdateSchemaContractTest,McpOAuth*Test,PrincipalTokenResolverTest,HeaderBasedAuthenticationMechanismTest,HeaderBasedSecurityConfigurationTest,ErrorChallengeSenderTest'
python3 -B -m unittest discover -s docs/mcp -p 'test_*.py'
git diff --check

Checklist

• Changes manually tested
• Automated Tests added/updated
• Documentation added/updated
• CLA Signed: DataStax CLA

MCP stack

Merges bottom up; row 1 is the bottom of the stack.

#	PR	Change	Issue
1	#2651	Show accepted update syntax in tool schemas	Fixes #2631
2	#2658	Describe every tool argument	Part of #2604
3	#2645	Close the command context after each call	Part of #2629
4	#2653	Return useful errors when setup fails	Fixes #2628
5	#2648	Keep payloads and credentials out of logs	Fixes #2635
6	#2649	Describe side effects and retry behavior	Fixes #2636
7	#2655	Validate commands like the HTTP API	Fixes #2632
8	#2656	Test request isolation, document tracing	Refs #2629
9	#2657	Reject unapproved browser origins	Part of #2630
10	#2659	Serve only protocol 2026-07-28	Part of #2625, #2626
11	#2669	Add opt-in OAuth authentication	Refs #2642, #2643

[erichare]

The November 3 alignment added deployment checks in #2634 for Authorization Bearer forwarding and database wake-up, plus permitted and denied database operations using the final identity contract, once agreed. #2654 tracks the gateway/platform and backend ownership needed for those checks.

The final subject and permission contract, token lifetime, and headless launch scope remain open. Resource-server acceptance of a JWT does not establish that the backend authorizes its identity correctly. Existing user-token behavior also needs to remain intact. These are integration dependencies alongside the local verification already recorded in this PR.

[github-actions]

📈 Unit Test Coverage Delta vs Main Branch

Metric	Value
Main Branch	56.74%
This PR	58.44%
Delta	🟢 +1.70%
✅ Coverage improved!

[github-actions]

Unit Test Coverage Report

Overall Project	58.44% -0.01%	🍏
Files changed	98.7%	🍏

File	Coverage
PrincipalTokenResolver.java	100%	🍏
ProtectedResourceMetadataResource.java	100%	🍏
HeaderBasedSecurityConfiguration.java	100%	🍏
McpOAuthMetadata.java	99.6% -0.4%	🍏
McpEndpointConfigSourceFactory.java	99.06%	🍏
HeaderBasedAuthenticationMechanism.java	98.42%	🍏
McpResource.java	88.53%	🍏
ErrorChallengeSender.java	85.34%	🍏
RequestContext.java	56.9% -2.25%	❌
FixedTokenResolver.java	0%	🍏
HeaderTokenResolver.java	0%	🍏

[github-actions]

📉 Integration Test Coverage Delta vs Main Branch (hcd-it)

Metric	Value
Main Branch	74.33%
This PR	74.08%
Delta	🔴 -0.25%
⚠️ Coverage decreased

[github-actions]

Integration Test Coverage Report (hcd-it)

Overall Project	74.08% -0.38%	🍏
Files changed	38.41%	❌

File	Coverage
RequestContext.java	89.66%	🍏
McpResource.java	82.37%	🍏
ErrorChallengeSender.java	77.31% -8.4%	🍏
McpEndpointConfigSourceFactory.java	72.77% -16.9%	🍏
PrincipalTokenResolver.java	68.42% -31.58%	❌
HeaderBasedAuthenticationMechanism.java	64.43% -33.99%	❌
HeaderBasedSecurityConfiguration.java	22.22% -77.78%	❌
McpOAuthMetadata.java	15.6% -84.4%	❌
FixedTokenResolver.java	0%	🍏
HeaderTokenResolver.java	0%	🍏
ProtectedResourceMetadataResource.java	0%	❌

[github-actions]

📉 Integration Test Coverage Delta vs Main Branch (dse69-it)

Metric	Value
Main Branch	72.98%
This PR	72.76%
Delta	🔴 -0.22%
⚠️ Coverage decreased

[github-actions]

Integration Test Coverage Report (dse69-it)

Overall Project	72.76% -0.38%	🍏
Files changed	38.41%	❌

File	Coverage
RequestContext.java	89.66%	🍏
McpResource.java	82.37%	🍏
ErrorChallengeSender.java	77.31% -8.4%	🍏
McpEndpointConfigSourceFactory.java	72.77% -16.9%	🍏
PrincipalTokenResolver.java	68.42% -31.58%	❌
HeaderBasedAuthenticationMechanism.java	64.43% -33.99%	❌
HeaderBasedSecurityConfiguration.java	22.22% -77.78%	❌
McpOAuthMetadata.java	15.6% -84.4%	❌
FixedTokenResolver.java	0%	🍏
HeaderTokenResolver.java	0%	🍏
ProtectedResourceMetadataResource.java	0%	❌