This post was originally published on this site

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.

MCP: The universal interface

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.

What’s new in Java SDK v1.0: Built for production workloads

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 & HttpMcpTransport: We introduced a clean transport layer abstraction alongside HttpMcpTransport. 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.

Get started with the Java SDK v1.0

We designed the MCP Toolbox Java SDK to be frictionless for enterprise teams. Just add the following dependency to your pom.xml:

code_block
<ListValue: [StructValue([('code', 'rn com.google.cloud.mcprn mcp-toolbox-sdk-javarn 1.0.0rn’), (‘language’, ”), (‘caption’, )])]>

Real-world example: The autonomous transit concierge

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.

The foundation: AlloyDB schema with native embeddings

We used AlloyDB for this implementation because it handles relational data and high-dimensional vectors natively. Set up your database tables with these statements:

code_block
<ListValue: [StructValue([('code', "– Enable necessary extensions for semantic search and embeddingsrnCREATE EXTENSION IF NOT EXISTS vector;rnCREATE EXTENSION IF NOT EXISTS google_ml_integration;rnrn– Table 1: Transit Policies (Unstructured Data for RAG)rnCREATE TABLE transit_policies (rn policy_id SERIAL PRIMARY KEY,rn category VARCHAR(50),rn policy_text TEXT,rn policy_embedding vector(768)rn);rnrn– Table 2: Intercity Bus Schedules (Structured Data)rnCREATE TABLE bus_schedules (rn trip_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),rn origin_city VARCHAR(100),rn destination_city VARCHAR(100),rn departure_time TIMESTAMP,rn arrival_time TIMESTAMP,rn available_seats INT DEFAULT 50,rn ticket_price DECIMAL(6,2)rn);rnrn– Table 3: Booking Ledger (Transactional Action Data)rnCREATE TABLE bookings (rn booking_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),rn trip_id UUID REFERENCES bus_schedules(trip_id),rn passenger_id VARCHAR(100),rn status VARCHAR(20) DEFAULT 'CONFIRMED',rn booking_time TIMESTAMP DEFAULT CURRENT_TIMESTAMPrn);"), ('language', 'lang-sql'), ('caption', )])]>

Mapping intents to SQL: The 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:

code_block
<ListValue: [StructValue([('code', 'kind: sourcernname: alloydbrntype: alloydb-postgresrnproject: my-projectrnregion: us-central1rncluster: my-clusterrninstance: my-instancerndatabase: postgresrn—rnkind: toolrnname: query-schedulesrntype: postgres-sqlrnsource: alloydbrndescription: Find available bus schedules between cities.rnparameters:rn – name: originrn type: stringrn description: The departure city name.rn – name: destinationrn type: stringrn description: The arrival city name.rn – name: limitrn type: integerrn description: Maximum number of schedules to return.rn default: 5rnstatement: |rn SELECT CAST(trip_id AS TEXT) AS trip_id, departure_time, ticket_pricern FROM bus_schedulesrn WHERE lower(origin_city) = lower($1) AND lower(destination_city) = lower($2)rn ORDER BY departure_time ASCrn LIMIT $3'), ('language', ''), ('caption', )])]>

For the complete YAML file, see the tools.yaml file in the mcp-toolbox-sdk-java repository.

Stateful agent architecture in Spring Boot

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:

  1. A declarative agent interface that manages the prompt, tools, and conversational memory via an HTTP session.

  2. A tool execution service that routes agent requests directly to the MCP Toolbox server.

code_block
<ListValue: [StructValue([('code', 'interface TransitAgent {rn @SystemMessage({rn "You are the Cymbal Transit Concierge.",rn "Use the 'querySchedules' tool for finding schedules.",rn "Use 'bookTicket' to execute transactions.",rn "Use 'searchPolicies' to look up luggage and pet rules."rn })rn String chat(@MemoryId String sessionId, @UserMessage String userMessage);rn}rnrn@Servicernclass TransitAgentTools {rn // These methods automatically invoke our MCP Toolbox server!rn @Tool("Query specific schedules between an origin and destination city.")rn public String querySchedules(String origin, String destination) { … }rnrn @Tool("Book a ticket for a passenger.")rn public String bookTicket(String tripId, String passengerName) { … }rnrn @Tool("Search transit policies for luggage and pet rules.")rn public String searchPolicies(String query) { … }rn}'), ('language', ''), ('caption', )])]>

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.

Connecting the dots: Listing, invoking, and executing tools in Java v1.0

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:

code_block
{rn System.out.println(“Successfully discovered ” + tools.size() + ” tools.”);rn});rnrn// 3. Invoking a Tool (Read-Only Data with Default Parameter Support)rn// “limit” is omitted: the SDK fills it from the default in the tool definitionrnString schedules = mcpClient.loadTool(“query-schedules”)rn .thenCompose(tool -> tool.execute(Map.of(rn “origin”, “New York”,rn “destination”, “Boston”)))rn .join().text();rnrn// 4. Executing a Transactional Tool (Using Bound Parameters)rnAuthTokenGetter toolAuthGetter = () -> CompletableFuture.completedFuture(myIdToken);rnrnString bookingConfirmation = mcpClient.loadTool(“book-ticket”, Map.of(“google_auth”, toolAuthGetter))rn // Bind the authenticated user context securely. bindParam returns a new immutablern // Tool, and the bound parameter is pruned from the definition exposed to the LLM!rn .thenCompose(tool -> tool.bindParam(“passenger_name”, “Jane Doe”)rn // Execute the mutable transactionrn .execute(Map.of(“trip_id”, “123e4567-e89b-12d3-a456-426614174000″)))rn .join().text();’), (‘language’, ”), (‘caption’, )])]>

Secure by default: authentication and deployment

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.

Application Default Credentials (ADC) & safety

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.

Deploying the fleet to Cloud Run

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.

Get started today

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.

Step 1: Add the Dependency

To start building with the SDK, add the following dependency to your Maven project’s pom.xml file:

code_block
<ListValue: [StructValue([('code', 'rn com.google.cloud.mcprn mcp-toolbox-sdk-javarn 1.0.0rn rn ‘), (‘language’, ”), (‘caption’, )])]>

Step 2: Explore Resources & Demos

Demo Application: To experience the Java SDK V1.0 for MCP Toolbox latest, try the sample application Cymbal transit project.

Gradle implementation

If your team uses Gradle instead of Maven, remember they will need to translate this dependency:

code_block
<ListValue: [StructValue([('code', "implementation 'com.google.cloud.mcp:mcp-toolbox-sdk-java:1.0.0'"), ('language', ''), ('caption', )])]>

Automatic version tracking

If you copy this setup into automated internal repositories, keep the XML comment 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!