Co-authors:Stenal Jolly, Strategic Cloud Engineer, Google Anubhav Dhawan**, Software Engineer, Google
Following the landmark announcement of MCP Toolbox v1.0, we're thrilled to announce that the MCP Toolbox Java SDK has officially reached version 1.0.
This release brings first-class, type-safe agent orchestration to one of the world's most widely adopted enterprise ecosystems. Java's mature architecture is purpose-built for rigorous demands, providing the high concurrency, strict transactional integrity, and robust state management required to safely scale mission-critical AI agents in production.
In this post, we'll tell you about what's new in Java SDK v1.0, show you a real-world example, and help you get started with your own implementation.
Today, developers face a compounding integration bottleneck: if you have N different AI models and M enterprise data sources, you must build, secure, and maintain N × M bespoke, custom connections. This lack of a unified integration layer forces engineering teams to rely on a fragmented web of ad-hoc pipelines. As a result, scaling an agentic architecture quickly becomes unsustainable, exposing sensitive enterprise databases to severe security vulnerabilities, fragmented access controls, and massive maintenance overhead.
Eliminating the fragmented web of custom integrations is the core problem solved by the Model Context Protocol (MCP). Acting as a universal interface—the "USB Type-C" for AI orchestration—MCP decouples models from data sources. Instead of writing custom or managed API integration code for every new model or database, developers write to a single, standardized protocol. This approach allows any MCP-compliant agent to securely and immediately interact with any MCP-enabled system. The MCP connection lets developers connect agents to real-world systems without building bespoke integrations for every new model.
When we announced the public Beta for the MCP Toolbox Java SDK, our goal was to bring first-class, type-safe agent orchestration to enterprise Java environments. Since then, we've collaborated with developers and open-source contributors to harden our APIs.
The v1.0 release marks a stable, backwards-compatible foundation suitable for enterprise workloads. Here's what's new and hardened since our v0.2 release:
Transport layer abstraction & HttpMcpTransportHttpMcpTransport. This feature decouples the core protocol logic from underlying HTTP clients, making it easy to swap network implementations or customize connection pooling.
Decoupled client authentication: To simplify enterprise security compliance, client authentication is now decoupled using CredentialsProvider and AuthMethods classes. Credentials are resolved asynchronously on every request, so teams can refresh tokens dynamically or plug in their own token source (Google OIDC via ADC ships in the box, anything else is a one-method interface).
Default parameter support: Native support for default values in tool parameters, reducing prompt payload sizes and enhancing agent reliability.
Pruning bound parameters: Sensitive parameters that are bound server-side (like tenant_id) are now automatically stripped from exposed tool definitions so the LLM can't manipulate them.
Version selection & session tracking: Standardized MCP version selection and robust session tracking ensure consistent protocol negotiation and conversation-state lifecycles.
HTTP credential exposure warnings: Added built-in detection that warns you at runtime when credentials are about to travel over a plaintext HTTP connection.
Generic client headers map: Easily attach custom corporate proxy headers, transaction tracing IDs, or correlation metadata to all outgoing requests.
We designed the MCP Toolbox Java SDK to be frictionless for enterprise teams. Just add the following dependency to your pom.xml:
To demonstrate the power of the Java SDK combined with AlloyDB, let's look at an enterprise use case.
Meet Cymbal Transit, a fictitious intercity bus network. Customers don't want to click through nested dropdown menus to plan a trip. They want to ask:
"I need to get from New York to Boston tomorrow morning. Can I bring my Golden Retriever? If so, book me the fastest trip."
To answer this question, an AI agent must cross-reference unstructured data (pet policies) with structured data (schedules and seat availability) and execute a transaction (booking)—all while maintaining the context of the conversation.
We used AlloyDB for this implementation because it handles relational data and high-dimensional vectors natively. Set up your database tables with these statements:
tools.yaml
The MCP Toolbox lets you define custom tools securely. Rather than granting the LLM direct database access, a tools.yaml configuration maps natural language intents directly to parameterized, safe queries:
For the complete YAML file, see the tools.yaml file in the mcp-toolbox-sdk-java repository.
The hardest part of building conversational AI in enterprise applications is managing state: when a user asks, "What times are available?" and follows up with, "Book the 8 AM one," the agent must remember prior context across turns.
Using the Java MCP Toolbox SDK with Spring Boot and LangChain4j, we can cleanly maintain conversational memory in the HTTP Session and we can cleanly separate the agent into two declarative components: A declarative agent interface that manages the prompt, tools, and conversational memory via an HTTP session.
A tool execution service that routes agent requests directly to the MCP Toolbox server.
Notice how the @MemoryId annotation abstracts session tracking: Spring Boot automatically correlates conversational context to the user's HTTP session. Meanwhile, LangChain4j and the MCP Toolbox handle schema translation and tool routing behind the scenes—no handwritten if/else intent parsing required.
By pairing the MCP Toolbox Java SDK with LangChain4j, we achieve clean separation of concerns and effortless state management:
Zero-boilerplate session management: The @MemoryId String sessionId parameter binds conversation history directly to the user's HTTP session.
Declarative agent contract: The TransitAgent interface defines the model's persona and system instructions without complex prompt templating.
Type-safe tool execution: The TransitAgentTools Spring service wraps remote MCP database tools as native Java methods.
This architecture ensures your agent remains modular: you can refine prompt guidance in the interface, manage user sessions automatically, and execute secure database queries through MCP Toolbox without tight coupling.
Now let's look under the hood of the TransitAgentTools interface. Inside those LangChain4j @Tool methods on our Spring @Service, the MCP Toolbox Java SDK handles the heavy lifting—bridging your Java service methods to the MCP tools defined in the tools.yaml file. In just a few lines of type-safe code, we can initialize our client using the new v1.0 decoupled authentication and headers abstractions:
Moving an AI agent to production requires rock-solid credential handling and an infrastructure that scales with demand. Let's look at how you can enforce credential safety across environments and deploy independently on Cloud Run.
By using the GoogleCredentialsProvider service, your Java app inherits its secure identity from its execution environment (whether local or in Google Cloud) through Application Default Credentials (ADC)—no hard-coded keys, with OIDC tokens minted and cached per audience under the hood. Furthermore, v1.0 offers HTTP Credential Exposure Warnings that automatically detect when credentials are about to travel over a plaintext HTTP connection and emit a runtime warning telling you to switch to HTTPS.
Because MCP Toolbox and the Spring Boot Agent are fully decoupled, they scale independently on Google Cloud Run to meet high concurrency and stateful conversation requirements.
To set up and configure Toolbox on Cloud Run, download the open-source MCP Toolbox for Databases and then follow the deployment guide.
With MCP Toolbox Java SDK v1.0, enterprise Java teams can wire Spring Boot and LangChain4j agents to the Toolbox server, and through it, to AlloyDB and every other supported data source. When you use the toolbox, arguments are validated against the tool definition before they leave the JVM, authentication is decoupled, and custom headers are attached to every outgoing request. The following implementation steps will help you get started.
To start building with the SDK, add the following dependency to your Maven project's pom.xml file:
**GitHub Repository**: [Java SDK for interacting with the MCP Toolbox for Databases](https://github.com/googleapis/mcp-toolbox-sdk-java)
**Official Documentation**: [MCP Toolbox for Databases](https://mcp-toolbox.dev/)
Demo Application: To experience the Java SDK V1.0 for MCP Toolbox latest, try the sample application Cymbal transit project.
If your team uses Gradle instead of Maven, remember they will need to translate this dependency:
If you copy this setup into automated internal repositories, keep the XML comment `<!-- {x-version-update...} -->` intact. It's required by the release manager's deployment scripts to automatically bump versions.
Now that you can integrate your modern agentic tools and servers to your enterprise Java applications with a stale MCP Toolbox Java SDK, get started today!