All chapters
  1. Start hereA protocol standardizes the call. It does not grant the permission
  2. Foundations · 1The primitive: a function, its arguments, its result, its side effects
  3. Foundations · 2Function calling: the model asks, your application executes
  4. Foundations · 3Client and server: process boundaries, JSON-RPC, errors and trust
  5. Foundations · 4What MCP is: host, client, server and what the protocol promises
  6. Protocol · 5Three surfaces: tools act, resources inform, prompts guide
  7. Protocol · 6A first MCP server: typed input, deterministic data, the raw exchange
  8. Protocol · 7Java and the SDKs: typed DTOs, validation and interoperability
  9. Protocol · 8Local or remote: stdio, HTTP, stateless requests and availability
  10. Platform · 9The database decision: direct SQL, a service boundary or an MCP adapter
  11. Platform · 10Sharing across teams: ownership, catalogs, contracts and versions
  12. Platform · 11Who gets access: users, agents, delegation and least privilege
  13. Platform · 12Enterprise authorization: tokens, audiences, gateways and no passthrough
  14. Platform · 13The threat model: injection, poisoned tools, confused deputies and egress
  15. Platform · 14Governance: who may publish, who approves, who answers the page
  16. Operations · 15Observability and audit: what was called, by whom, and why it was allowed
  17. Operations · 16Resilience: timeouts, retries, idempotency and overload at a shared server
  18. Operations · 17Testing and evaluation: contracts, authorization matrices and injection
  19. Reference · 18Advanced MCP: long tasks, large catalogs, tenants and evolving versions
  20. Reference · 19The ecosystem: SDKs, registries, gateways, identity and telemetry
  21. Reference · 20Enterprise reference architecture: one assessment platform, four teams
  22. Reference · 21Decision playbooks: function, API or MCP, and the records that explain why
  23. ReferenceGlossary
  24. AboutAbout this site and its sources
Protocol · 7

Java and the SDKs: typed DTOs, validation and interoperability

The same contract as a Java record with validation, as a Pydantic model and as JSON Schema; what the official SDKs generate for you, and what makes a Python client and a Java server agree.

You will understand
Why one JSON Schema is the contract, and a Java record, a Pydantic model or Bean Validation are only ways to keep it.
You will be able to compare
What the official SDKs do for you, as their documentation says on 2026-11-18, and what they leave to you.
You will know
What a Python client and a Java server must agree on, and a checklist to test it.

The claims team runs on Java. It has used get_roof_assessment through the shared server for a quarter, and now it wants to run its own copy of the roof tool inside its Spring application, next to its claims data. A developer builds it in two days. The record class looks right, the Bean Validation annotations look right, the unit tests pass.

Then the underwriting agent's host, a Python application, calls the Java version for SUB-1004. The reply carries submissionId instead of submission_id, because the Java serializer wrote the record's component name. The Python side checks the reply against the tool's output schema and refuses it: the required field /submission_id is missing and /submissionId is not allowed. Nothing was wrong in Java. Nothing was wrong in Python. The two programs had never agreed on one written contract; each had its own idea of the DTO.

(The Java copy is this page's illustration. The example has no Java MCP server; the refusal itself is real and is run below with the example's validator.)

This page is about that agreement. Every architecture on this site returns the same PropertyAssessment. The question here is how three languages and four libraries keep returning the same thing, and what the official MCP SDKs do or do not do to help.

One contract, many ways to write it down#

A contract here is the written description of a value that both sides of a call accept as binding: which fields exist, their types, which are required, which values are allowed. Each language has its own way to hold one.

A Java record is a class declared by its components, for which Java derives the constructor, the accessors and equals. A tiny example: record SubmissionId(String value) {}. Its compact constructor can reject bad values before any instance exists. The primitive runs the example's record.

Bean Validation (now called Jakarta Validation) is a Java standard that puts constraints on fields and parameters as annotations, such as @NotNull on a field, and runs them through a validator. Pydantic is a Python library that validates data against classes declared with type hints and produces a JSON Schema from them. Spring Boot is a Java framework that wires an application's controllers, services and repositories together and, among much else, runs Bean Validation on method calls when told to.

Each of these keeps the contract inside one language. None of them is visible to the other side of the wire. What crosses the wire is JSON, and what both sides can read is a JSON Schema: a JSON document that describes which fields a JSON value must have and what each may contain, defined on Function calling. MCP puts one in every tool definition (inputSchema, and optionally outputSchema). Schema generation is producing that JSON Schema from code, such as a Pydantic model or an annotated method, instead of writing it by hand.

So the design rule of this page is short. The JSON Schema is the contract. The record, the annotations and the Pydantic model are three implementations of it, and each must be tested against it.

Before AI. A backend engineer has lived this with SOAP and WSDL, with OpenAPI, and with Avro or Protocol Buffers on a Kafka topic. The schema in the registry is the contract; the Java class generated from it, or hand-written next to it, is one consumer's copy. Teams that let each service's classes be "the contract" got the camelCase-versus-snake_case outage sooner or later.

The smallest primitive: the contract as JSON Schema#

The example writes the DTO's contract once, in domain.py, as DTO_SCHEMA. The comment above it says what it is for: "The DTO as a JSON Schema: the tool's outputSchema and the shared contract with Java." An excerpt:

{"type": "object",
 "properties": {
   "submission_id": {"type": "string", "pattern": "^SUB-[0-9]{4}$"},
   "property_id": {"type": "string", "pattern": "^PROP-[0-9]{4}$"},
   "roof_age_years": {"type": ["integer", "null"], "minimum": 0, "maximum": 150},
   "assessment_status": {"type": "string", "enum": ["complete", "no_record", "pending"]}
 },
 "required": ["submission_id", "property_id", "roof_age_years", "roof_material", "evidence_source",
              "evidence_id", "assessed_at", "policy_version", "assessment_status"],
 "additionalProperties": false}

(Four of the nine properties shown; the enum lists ASSESSMENT_STATUSES from the same file.) The input side is as small. This is the get_roof_assessment entry the server sent the underwriting agent's MCP client in the recorded HTTP session (out/mcp_transcript_http.json, message 8), run in a scratch copy on 2026-11-18:

{"name": "get_roof_assessment",
 "inputSchema": {"type": "object",
                 "properties": {"submission_id": {"type": "string", "pattern": "^SUB-[0-9]{4}$",
                                                  "description": "The submission, for example SUB-1004."}},
                 "required": ["submission_id"], "additionalProperties": false}}

Neither schema names a dialect. Normative (MCP specification 2026-07-28): a schema without a $schema field is JSON Schema 2020-12; every client and server must support that dialect and should document any others; an implementation must not fetch a $ref that points at a network address on its own. So a Python client and a Java server that read this inputSchema are reading the same language, by rule, not by luck. That is the first thing they agree on.

The same contract in four notations#

Here is the roof DTO, or a slice of it, in each notation. Only the first two were run here. The others are documented shape; not run here, written from documentation read on 2026-11-18 and labelled as such.

JSON Schema (the contract)

The schema above. It is the only notation both sides can read, the only one MCP carries, and the only one a gateway or a test can check without running either language. In the example it is DTO_SCHEMA (the tool's outputSchema) and the input_schema of each catalog record in catalog.py.

Java record (run)

The record in java/AssessmentService.java validates in its compact constructor, so no invalid instance can exist. The primitive quotes it and its eight-line run. What matters on this page is one line of its toJson() method: the record's components are camelCase (submissionId), and the method writes snake_case names ("submission_id") by hand. The wire names are a decision, written down in code, not a side effect of the class.

Bean Validation + Spring (documented shape)

Not compiled or run here; a shape modelled on the example in Spring Boot's validation page (Spring Boot 4.1.2), read on 2026-11-18, which uses @Service, @Validated and a @Size constraint on a parameter. The class name and the repository call are this site's sketch.

// sketch: documented shape; not compiled or run here
@Service
@Validated
public class RoofAssessmentService {
    public PropertyAssessment getRoofAssessment(@Size(min = 8, max = 8) String submissionId) {
        return repository.findBySubmissionId(submissionId).orElseThrow(NotFound::new);
    }
}

The page says method validation runs when a Bean Validation implementation (such as Hibernate Validator, typically via spring-boot-starter-validation) is on the classpath and the class carries @Validated. Notice what the sketch does not say: a length of 8 accepts XYZ-1004. The pattern ^SUB-[0-9]{4}$ lives in the record and in the schema. The constraint definitions of Jakarta Validation 3.1 (its section 8) were not read here, so this page names no other built-in constraint and states no null rule; write the null rule explicitly in the record.

Pydantic (documented shape)

Not run here; a shape built from the Pydantic JSON Schema page (now on pydantic.dev) read on 2026-11-18. The page says generated schemas comply with JSON Schema Draft 2020-12, and that model_json_schema() produces the validation schema by default.

# sketch: documented shape; not run here
from typing import Literal

from pydantic import BaseModel, ConfigDict, Field


class PropertyAssessment(BaseModel):
    model_config = ConfigDict(extra="forbid", strict=True)
    submission_id: str = Field(pattern=r"^SUB-[0-9]{4}$")
    property_id: str = Field(pattern=r"^PROP-[0-9]{4}$")
    roof_age_years: int | None = Field(ge=0, le=150)
    assessment_status: Literal["complete", "no_record", "pending"]


schema = PropertyAssessment.model_json_schema()

Writing the class is not the hard part. Tools Engineering: types teaches in depth what generation loses, what Pydantic's defaults do and how Java deserializers fill in nulls. This page takes that as known and asks the question that appears once two teams own two copies: does each copy still match the one contract?

Run it: does the Java DTO satisfy the shared schema?#

The test is short. Run the Java program, take its DTO, and validate it against DTO_SCHEMA with the example's own validator (schema.py, a subset of 2020-12 written for the example). Then change the payload the way a second implementation would drift, and see which drift the contract catches. The script lives in the scratch folder, not in the example:

"""Check the Java program's DTO against the shared JSON Schema (DTO_SCHEMA) with the example's validator."""
import json
import subprocess
import sys

sys.path.insert(0, sys.argv[1])
from domain import DTO_SCHEMA  # noqa: E402
from schema import validate  # noqa: E402

rows = json.loads(subprocess.run(["java", "AssessmentService.java", "--json"], cwd=sys.argv[1] + "/java",
                                 capture_output=True, text=True, check=True).stdout)
java_dto = rows[0]["result"]["data"]
print("java DTO vs DTO_SCHEMA:", validate(java_dto, DTO_SCHEMA) or "valid")

camel = {"submissionId" if k == "submission_id" else k: v for k, v in java_dto.items()}
print("camelCase name on the wire:", [v["path"] + " " + v["keyword"] for v in validate(camel, DTO_SCHEMA)])

as_text = dict(java_dto, roof_age_years="22")
print("roof age as a string:", [v["path"] + " " + v["keyword"] for v in validate(as_text, DTO_SCHEMA)])

new_status = dict(java_dto, assessment_status="superseded")
print("a status Java added:", [v["path"] + " " + v["keyword"] for v in validate(new_status, DTO_SCHEMA)])

as_float = dict(java_dto, roof_age_years=22.0)
print("22.0 instead of 22:", validate(as_float, DTO_SCHEMA) or "valid")

Run on 2026-11-18 with openjdk version "23.0.1" 2024-10-15 and /opt/homebrew/bin/python3, in a scratch copy of examples/uw-mcp:

java DTO vs DTO_SCHEMA: valid
camelCase name on the wire: ['/submission_id required', '/submissionId additionalProperties']
roof age as a string: ['/roof_age_years type']
a status Java added: ['/assessment_status enum']
22.0 instead of 22: valid

A successful run proves one thing: the Java record's output for SUB-1004 (roof 22 years, EV-ROOF-0412, policy 2026.2) is a valid instance of the contract the Python server publishes. It does not prove that every Java path writes valid output; it is one golden payload, and a real contract test sends many.

Read the drift lines one at a time. The camelCase name is the opening scene, refused with two paths. A number sent as text is refused by type. A new status that one team added and the other never heard of is refused by enum, which is the right answer: an unknown status is a breaking change, not an extra. The last line is the quiet one. JSON Schema counts 22.0 as an integer, so the contract accepts it, while a strict Java or Python type may not. The contract and the code can disagree in both directions, which is why the test runs against the code, not only against the schema.

Diagram: One contract, four notations · only the schema travels

Read the columns left to right. On the left, three language-specific sources: a Pydantic model, a Java record, Bean Validation annotations on a Spring service. Each either generates the JSON Schema or is tested against it. In the middle, the one contract: the JSON Schema in the tool definition, 2020-12 by default. On the right, what reads it on the wire: the host's MCP client, the server's SDK check, and contract tests. Nothing on the left crosses the wire.

  1. Sources in one language
    1. Pydantic model: A Python class with Field constraints. Its documentation says model_json_schema() produces a 2020-12 schema, the validation schema by default.
    2. Java record: The record in java/AssessmentService.java validates in its compact constructor and writes snake_case names in toJson().
    3. Bean Validation on a Spring service: Constraint annotations checked when the framework intercepts the call (a @Validated class and a validator on the classpath).
  2. The contract
    1. JSON Schema in the tool definition: The only notation both sides can read. inputSchema for arguments, outputSchema for the result. In the example, DTO_SCHEMA and the catalog's input_schema.
    2. generated, or tested against: Python and TypeScript SDKs generate the schema from code, as documented; the Java SDK takes a schema as a Map or as JSON text. Either way one file is the source and the rest are tested against it.
  3. Readers on the wire
    1. host's MCP client (Python): Reads tools/list, shows the model the inputSchema, and checks structuredContent against the outputSchema.
    2. server's SDK check (Java): The MCP Java SDK's modern server checks arguments against inputSchema before the handler runs, as documented on 2026-11-18.
    3. contract tests: The same payloads validated on both sides in each build: valid ones pass everywhere, each drift fails everywhere.

The diagram puts the four notations around the one contract. Read it left to right: each language-specific source either generates the schema or is tested against it, and only the schema travels.

The Spring shape: controller, service, repository#

The spec of this site asks for a Java service boundary with repository and service separation. The example runs that separation in plain Java (AssessmentService over an AssessmentRepository interface). A Spring application expresses the same split with annotations. The following is documented shape; not run here, from the Spring Framework 7.0.10 and Spring Boot 4.1.2 pages read on 2026-11-18.

LayerSpring annotation (as documented)What it owns in the roof example
Presentation (adapter)@Controller (a REST controller)HTTP mapping, request body validation, error shape for HTTP clients
Service (domain)@Service, with @Validated for method validationThe rules: scope check, idempotency, R-ROOF-03; the transaction
Persistence@RepositoryQueries; the documentation says it also marks automatic exception translation
MCP adapter (not Spring-specific)none required; a server from the MCP Java SDKTool definitions, tools/call dispatch, the MCP error shape

The framework documentation says @Repository, @Service and @Controller are specializations of @Component for the persistence, service and presentation layers. The point for MCP is the last row. An MCP server is one more adapter beside the REST controller. It calls the same service; it never copies a rule. That is how the example's Python server is built (ServiceGateway.invoke calls AssessmentService for every tool), and it is the shape a Java version should keep.

Validation then happens in up to four places, and they must agree. The MCP Java SDK's modern server page says arguments are checked against inputSchema before the handler runs. Spring MVC validates a request body marked @Valid and raises MethodArgumentNotValidException, or runs method validation and raises HandlerMethodValidationException, depending on the method signature. Spring Boot's method validation checks a @Validated service. And the record's compact constructor checks the value itself. Four validators, one contract: the folded block "Four validators, one contract" below says which to trust for what.

Diagram: Two adapters, one service · where each check runs in a Java version

Rows are the layers of a Java service; columns are the two doors into it. The REST controller and the MCP server are both adapters. Each validates at its own door with its own error shape. Both call the same service, which owns the rules and validates again, and the same repository. Documented shape from the Spring and MCP Java SDK pages; the example runs the same split in plain Java.

  1. Adapter
    1. REST controller: Spring MVC validates a @Valid request body (MethodArgumentNotValidException) or runs method validation (HandlerMethodValidationException), as the Spring page says.
    2. MCP server (Java SDK): Arguments are checked against inputSchema before the handler; a failure becomes a tool result the model can read. Authorization sits in servlet filters in front of the transport.
  2. Service
    1. @Service with @Validated: The one place the rules live. Method validation runs when the framework intercepts the call. Both adapters call it; neither copies a rule.
    2. record constructor: The compact constructor rejects an invalid PropertyAssessment in any environment, with or without Spring.
  3. Repository
    1. @Repository: Queries behind an interface. The Spring page says @Repository also marks automatic exception translation.

The official SDKs, as documented on 2026-11-18#

Ecosystem pattern: most teams do not write the protocol layer themselves; they use an official SDK. The MCP SDK page lists tiers: TypeScript, Python, C#, Go, Rust and Ruby in Tier 1, Java in Tier 2, Swift, PHP and Kotlin in Tier 3. The same page warns that "SDKs adopt new protocol revisions on their own schedules", so the revision an SDK speaks is a property of that SDK version, not of MCP.

An MCP SDK is a library that implements the protocol for one language: messages, transports, and a way to declare tools. The MCP Java SDK is the official one for Java, maintained with Spring AI. The table compares three SDKs on what their documentation, read today, says they do. Where it does not say, the cell says so.

QuestionPython SDK (v2)TypeScript SDK (v2)Java SDK
Tier on the SDK pageTier 1Tier 1Tier 2
Revisionsimplements 2026-07-28 and serves 2025-era clients at onceimplements 2026-07-28; the README read does not say whether v2 serves 2025-11-25 clientsmodern 2026-07-28 and legacy 2025-11-25 and earlier, both supported
Where a tool's input schema comes from"from your type hints" (decorator servers); how hints become a schema is not said on the page readStandard Schema objects (Zod v4, Valibot, ArkType named); the example passes a Zod objectgiven as a Java Map or as JSON text; no schema generated from a Java type is shown
Checks arguments against the schemathe pages read do not saythe pages read do not sayyes: before the handler runs; output checked against outputSchema when declared
Transportsstdio, Streamable HTTP (plus sse_client, in-memory for tests); WebSocket removedstdio, Streamable HTTP; middleware for Node, Express, Fastify, Honostdio, Streamable HTTP (servlet server, JDK HttpClient client); Spring transports from Spring AI 2.1+
Authorization helppoints to OAuth (client) and authorization (server) pages; detail not on the page read"auth helpers" (server), "OAuth helpers" (client)none built in: authentication and authorization belong in servlet filters in front of the transport
Main class or package namedMCPServer (from mcp.server import MCPServer; the FastMCP name was removed)@modelcontextprotocol/server, @modelcontextprotocol/clientio.modelcontextprotocol.sdk:mcp; API reference mcp-core 2.2.0; Java 17 or later

Two rows decide most designs. The schema row: in Python and TypeScript the schema is generated from code, so the code is the source and a test must pin the generated output; in Java, as documented, you hand the SDK a schema, so the schema file can be the source and the record must be tested against it. The authorization row: no SDK makes the permission decision for you. The Java page is the most explicit, and it matches this site's first primitive. A protocol standardizes the call. It does not grant the permission.

Common confusion. "Official SDK" does not mean "conformant". The tier page sets Tier 2 at an 80% pass rate on the conformance suite and Tier 1 at 100%. An SDK can be official, current and still miss a rule your server depends on. Test the behavior you rely on, at your boundary.

What makes a Python client and a Java server agree#

Return to the claims team. Its Java server and the underwriting agent's Python host meet only on the wire. Five agreements decide whether they work together, and four of them are fixed by the specification.

The protocol revision. Normative (MCP specification 2026-07-28): every request carries io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in _meta; a request without them is rejected with -32602 (HTTP 400); an unsupported version gets -32022 with the supported versions in data. A Python host on a 2025-era SDK and a modern-only Java server will not meet at all. The Java SDK supports both eras; check which era your Python SDK version speaks before you assume.

The schema dialect. 2020-12 unless a schema says otherwise, as above. A Java team that pastes a draft-07 schema from an old project must declare $schema, and the other side must support it or answer with an error.

The error shapes. An unknown tool is a JSON-RPC error -32602; a failed or refused execution is a result with isError true. Codes -32020 to -32099 belong to the specification; an implementation must not invent codes there, and application codes should sit outside the whole reserved range. The example's -31403 for a missing scope is such an application code. A Java server that maps its exceptions to -32050 is breaking a MUST.

The _meta keys. Keys whose prefix's second label is modelcontextprotocol or mcp are reserved; vendor keys use reverse DNS (the example uses example.insurer/correlationId). traceparent, tracestate and baggage are reserved for trace context in W3C format, which is how one trace can cross from a Python host into a Java server. clientInfo is self-reported and must not drive security decisions.

The data contract. The one agreement the specification does not make for you: field names, types, nulls, enums, numbers. That is the JSON Schema, and it is only real if both sides are tested against it.

CheckHow to test itWhat fails without it
Same protocol revision in every requestsend server/discover from the client's SDK; log protocolVersion per request-32022, or a legacy client stuck at 400
Schemas in 2020-12, or $schema declaredlint every inputSchema and outputSchema in the builda keyword read differently on each side
No network $ref in any schemaschema lint; refuse external refsa validator that fetches URLs on a server
Wire names fixed (snake_case here)golden payloads validated against the schema on both sides/submissionId additionalProperties
Enums closed and versioneda new value is a new schema version/assessment_status enum in production
Numbers and nulls agreedsend 22.0, null, a missing field to both stacksone side accepts what the other refuses
Error codes outside the reserved range; two error channels kept apartcontract test per error casea client that reads a refusal as success
Trace context in _metaone trace id seen in both services' spansan incident that stops at the language boundary

What goes wrong without a shared contract#

Without one written contract, each implementation is its own truth. The failures are quiet. A renamed field breaks one consumer on the day it deploys. A new enum value reaches a client that treats it as an error, or worse, as the closest known value. A Java server and a Python server for the same tool accept different inputs, so a model's request succeeds on one and fails on the other.

The example has one real schema change, and it shows how a contract makes the failure loud instead. Version 1 of get_roof_assessment took property_id; version 2 takes submission_id. In this site's own case UW-M07, a client built for version 1 calls version 2 and gets invalid_arguments with two paths, /submission_id (required) and /property_id (not allowed), and the deprecated version is named. Nothing ran with a wrong argument. Sharing across teams turns that into a versioning and deprecation process.

In a coding agent. A company's repository server is written in Go; the developer's coding agent is a TypeScript application; the issue tracker server is in Python. open_pull_request has one inputSchema, and three SDKs read it. The coding agent's harness validates arguments before it sends them; the Go server validates again before it acts. If either side generated its own idea of the schema, a field such as draft: true can be dropped on the way and a draft becomes a real pull request. Harness Engineering covers the runtime that holds that check.
What this is not. This page does not teach type hints, generated schemas, Pydantic defaults or Java deserializer settings in depth; Tools Engineering: types does. Typed data contracts in general, and evolving them without breaking readers, belong to https://schema.sammuthu.com. Each SDK as a product, with its own section, is on Ecosystem.

Security and governance notes#

Security note. A schema is a validation contract, not a permission. get_roof_assessment validates SUB-2001 as a perfectly shaped id; the business-unit check refuses it (UW-M11). Every SDK in the table leaves authorization to you, and the Java SDK says so in one sentence. Also treat schemas as input: the specification forbids automatic network $ref and asks for bounds on composition keywords, because a hostile schema can make a validator fetch URLs or burn CPU.
Governance note. Name the owner of the contract, not only of the code. In the example the schema belongs to the assessment domain (owner team property-risk-data in the catalog), and the server maintainer ships it. A second implementation in another language, like the claims team's copy, needs the same owner's review before its tool is listed, and the same contract tests in its build.

Checklist for Monday#

Exercises#

  1. The Java team's Spring service validates @Size on submissionId, and the MCP Java SDK validates inputSchema. Which check can be removed?
  2. A Python server generates its inputSchema from type hints. A Java client hard-codes the schema from last month. What test catches the drift, and on which side does it run?
  3. A Java server answers a missing scope with JSON-RPC code -32050. What is wrong, and what would you use?
AnswersOne line each
  1. Neither: the SDK check protects the protocol boundary, the service check protects every other adapter (the REST controller); keep both, and tighten the service check to the contract's pattern, since a length of 8 also accepts XYZ-1004.
  2. A contract test in the Python server's build that compares the generated schema with the published one, plus golden payloads the Java client sends in its own tests; drift then fails a build instead of a call.
  3. -32020 to -32099 is reserved for the specification and must not carry invented codes; use HTTP 403 with insufficient_scope and an application code outside -32768 to -32000, as the example does with -31403.
Four validators, one contractSDK schema check, Spring MVC, method validation and the record: what each is for

A Java version of uw-assessment can validate the same argument four times: the MCP SDK against inputSchema, Spring MVC on a request body, Spring method validation on the service, and the record's compact constructor. That looks wasteful. It is not, if each check has a job.

The SDK check is the protocol boundary. It answers a model's malformed request with a result the model can correct, before any of your code runs. As documented, the Java SDK does this before the handler. Its rules come from the schema, so it is exactly as good as the schema.

The Spring MVC check belongs to the REST adapter, the other door into the same service. Its exceptions (MethodArgumentNotValidException or HandlerMethodValidationException, depending on the signature, as the Spring page says) are mapped to an HTTP error shape. The MCP adapter never sees them.

Method validation on the service and the compact constructor protect the domain from every adapter, including the ones not written yet. The difference between them is reach. Method validation runs when the framework intercepts the call, which the Spring Boot page ties to @Validated on the class and a validator on the classpath. The constructor runs whenever the value is built, in any environment, including a unit test without Spring.

This site's recommendation: let the SDK check and the record carry the contract's rules, generated from or tested against the one schema; keep framework validation for the HTTP adapter; and map every validator's failure to the same error code (invalid_arguments) with a JSON Pointer path, so a client cannot tell which layer refused. The danger is not duplication. It is four validators that disagree, which the golden-payload test above is there to catch.

Who owns the schema when the SDKs disagree about where it comes fromGenerated in Python and TypeScript, supplied in Java: picking the source per tool

The SDK table hides an asymmetry. As documented today, the Python SDK takes a decorated function's schema from its type hints and the TypeScript SDK from a Standard Schema object such as a Zod schema; both generate JSON Schema from code. The Java SDK's modern server page shows the schema supplied as a Map or as JSON text. A tool implemented in all three has two natural sources of truth and one consumer of a file.

Three designs work. Code first in one language: the Python model is the source, its generated schema is published as an artifact, and the Java side loads that file into Tool.builder and tests its record against it. Schema first: a reviewed schema file is the source; Python and TypeScript generate their models from it or test their generated schema for equality. Per-tool ownership: whichever team owns the domain (here the assessment domain) owns the file, whatever language it writes.

What fails is the fourth design, the default one: each team writes its own model and lets its own SDK generate a schema. Then two servers publish two schemas under one tool name, and a host that caches tools/list from one may send arguments the other refuses. Generators also differ in detail: Pydantic's page says the validation schema and the serialization schema can differ, and it puts nested models under $defs; a hand-written Java Map may inline them. Both are valid 2020-12, and a byte comparison of the two fails while a semantic comparison passes.

This site's recommendation: one schema file per tool version, owned by the domain team, published with the catalog record; generated schemas are compared to it semantically in every build; the Java side loads it rather than retyping it.

SDK revision lag is an operational riskTiers, conformance rates and a fleet that speaks two eras

The SDK page says each SDK adopts new revisions on its own schedule. The tier page, read for this site's source pack, makes that concrete: Tier 1 SDKs pass the full conformance suite and ship new features before a specification release; Tier 2 passes 80% and ships new features within six months. Java is Tier 2 today. A platform with Python hosts and a Java server can therefore spend months in a state where the newest revision is available on one side only.

The documented support for both eras softens this. The Python SDK v2 serves 2026-07-28 and 2025-era clients at once, and the Java SDK supports both, with legacy explicitly not deprecated there. The TypeScript README read today names only 2026-07-28. Mixed fleets are therefore normal, and the transport rules for detecting the other side's era are on Local or remote.

Treat it like any dependency with a protocol inside. Pin SDK versions per service. Record, per request, the revision used (the _meta field makes this cheap, and with no protocol session there is no other place it lives). Put a conformance check for the behaviors you depend on (header validation, -32022 handling, the two error channels) in the build of each service, because an 80% pass rate says nothing about which 20% you need. And read each SDK's changelog for renames before upgrading: the Python v2 rename of FastMCP to MCPServer removed the old import path instead of deprecating it.

In one breath#

The contract between a Python client and a Java server is the JSON Schema in the tool definition, read as 2020-12 by rule; a Java record, Bean Validation, Spring layers and a Pydantic model are implementations of it, each tested against it with the same golden payloads. The specification also fixes the per-request revision in _meta, the reserved error codes and _meta keys, so those agree if both sides follow it. The official SDKs differ in where a schema comes from and what they check, and none of them decides who may call a tool.

So far the protocol has been carried without much thought about how: a pipe in the stdio transcript, HTTP in the recorded session. The carrier is not a detail. It decides who starts the server, where its credentials live, what a crash looks like, and whether three instances behind a load balancer can share the work. That is Local or remote.