Spring AI

Treat converter output as best-effort: prefer provider-native JSON/structured-output modes when available, lower temperature, add retries around parse failures, validate the deserialized POJO (Bean Validation), enrich the schema with field descriptions, and log/alert on non-conformance.

Treat every tool as an attack surface: the model (steered by user input) chooses which tools to call and with what arguments. Validate arguments, enforce authorization inside the tool (via ToolContext identity, not model-supplied ids), gate destructive actions with human approval, limit result size, and add observability.

McpSyncClient is blocking — calls return results directly. McpAsyncClient is reactive — calls return Reactor Mono/Flux and never block a thread. You pick via spring.ai.mcp.client.type=SYNC or ASYNC; async fits reactive/WebFlux stacks, sync fits imperative apps.

You write a class implementing CallAdvisor (for blocking calls) and/or StreamAdvisor (for streaming), mutate the request, delegate to the next advisor in the chain, then optionally transform the response. getOrder() decides its position — a lower order runs earlier/further from the model. If you support both call() and stream(), you implement both interfaces so the two paths behave the same.

MCP buys interoperability and reuse — publish tools once, consume third-party tools without custom code. The cost is a process/network hop: latency, failure modes, auth/trust, and tool-name governance. Use in-process @Tool beans when everything lives in one app; use MCP across process, team, or vendor boundaries.

Design two paths: an offline ETL (read, chunk, enrich, embed, write to VectorStore) and an online query path (retrieve with SearchRequest, augment, generate). Tune chunking, topK, threshold, and metadata filters; measure retrieval quality and guard against empty-context hallucination.