[erichare]

What this PR does:

Applies the existing command validation before MCP schema lookup or execution. Empty and oversized insert batches and invalid find options return the same error code and reason as HTTP. Both transports use one error mapper.

Adds an MCP guide covering the endpoint, results, and command validation.

Which issue(s) this PR fixes:

Fixes #2632.

Verification

46 focused tests passed with 0 failures, 0 errors, and 0 skips at 078cf84fd, this PR's commit in the rebuilt stack. The format check found 0 non-complying files out of 1,217. The packaged MCP integration suite was not rerun locally after the rebuild. CI runs the unit and DSE/HCD integration suites on this push.

JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-21.jdk/Contents/Home ./mvnw -B -ntp com.spotify.fmt:fmt-maven-plugin:check test -DskipITs -Dxml-format.skip=true -Dsurefire.failIfNoSpecifiedTests=false -Dquarkus.http.test-port=19089 '-Dtest=McpCommandValidationTest,McpResourceTest,McpSetupErrorsTest'

Manual client checks were not run.

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

[github-actions]

📈 Unit Test Coverage Delta vs Main Branch

Metric	Value
Main Branch	56.74%
This PR	57.99%
Delta	🟢 +1.25%
✅ Coverage improved!

[github-actions]

Unit Test Coverage Report

Overall Project	57.99% -0.01%	🍏
Files changed	65.85%	🍏

File	Coverage
McpResource.java	88.4% -3.06%	❌
FrameworkExceptionMapper.java	31.7%	🍏

[github-actions]

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

Metric	Value
Main Branch	72.98%
This PR	73.07%
Delta	🟢 +0.09%
✅ Coverage improved!

[github-actions]

Integration Test Coverage Report (dse69-it)

Overall Project	73.07% -0.01%	🍏
Files changed	65.85%	🍏

File	Coverage
FrameworkExceptionMapper.java	88.72%	🍏
McpResource.java	82.17% -3.04%	❌

[github-actions]

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

Metric	Value
Main Branch	74.33%
This PR	74.41%
Delta	🟢 +0.08%
✅ Coverage improved!

[github-actions]

Integration Test Coverage Report (hcd-it)

Overall Project	74.41% -0.01%	🍏
Files changed	65.85%	🍏

File	Coverage
FrameworkExceptionMapper.java	88.72%	🍏
McpResource.java	82.17% -3.04%	❌