Core

Overview

The package provides a java interface to the MCP Toolbox service, enabling you to load and invoke tools from your own applications.

Installation

This SDK is distributed via a Maven Central Repository.

Maven

Add the dependency to your pom.xml:

<dependency>
    <groupId>com.google.cloud.mcp</groupId>
    <artifactId>mcp-toolbox-sdk-java</artifactId>
    <!-- Replace 'VERSION' with the latest version from https://mvnrepository.com/artifact/com.google.cloud.mcp/mcp-toolbox-sdk-java -->
    <version>VERSION</version>
    <scope>compile</scope>
</dependency>

Gradle

dependencies {
    // Replace 'VERSION' with the latest version from https://mvnrepository.com/artifact/com.google.cloud.mcp/mcp-toolbox-sdk-java
    implementation("com.google.cloud.mcp:mcp-toolbox-sdk-java:VERSION") 
}

Quickstart

Here is the minimal code needed to connect to a MCP Toolbox and invoke a tool.

import com.google.cloud.mcp.McpToolboxClient;
import java.util.Map;

public class App {
    public static void main(String[] args) {
        // 1. Create the Client
        McpToolboxClient client = McpToolboxClient.builder()
            .baseUrl("https://my-toolbox-service.a.run.app/mcp") 
            .build();

        // 2. Invoke a Tool
        client.invokeTool("get-toy-price", Map.of("description", "plush dinosaur"))
            .thenAccept(result -> {
                // Pick the first item from the response.
                System.out.println("Tool Output: " + result.content().get(0).text());
            })
            .exceptionally(ex -> {
                System.err.println("Error: " + ex.getMessage());
                return null;
            })
            .join(); // Wait for completion
    }
}

For a detailed example, check the ExampleUsage.java file in the example folder of Java SDK Repo.

// Async (Non-blocking)
client.invokeTool("tool-name", args).thenAccept(result -> ...);
// Sync (Blocking)
ToolResult result = client.invokeTool("tool-name", args).join();

Usage

Load the Client

The McpToolboxClient is your entry point. It is thread-safe and designed to be instantiated once and reused.

// Local Development
McpToolboxClient client = McpToolboxClient.builder()
    .baseUrl("http://localhost:5000/mcp")
    .build();

// Cloud Run Production
McpToolboxClient client = McpToolboxClient.builder()
    .baseUrl("https://my-toolbox-service.a.run.app/mcp")
    // .apiKey("...") // Optional: Overrides automatic Google Auth
    .build();

Load a Toolset

You can load all available tools or a specific subset (toolset) if your server supports it. This returns a Map of tool definitions.

// Load all tools (alias for listTools)
client.loadToolset().thenAccept(tools -> {
    System.out.println("Available Tools: " + tools.keySet());
    
    tools.forEach((name, definition) -> {
        System.out.println("Tool: " + name);
        System.out.println("Description: " + definition.description());
    });
});

// Load a specific toolset (e.g., 'retail-tools')
client.loadToolset("retail-tools").thenAccept(tools -> {
    System.out.println("Tools in Retail Set: " + tools.keySet());
});

Load a Tool

If you know the specific tool you want to use, you can load its definition directly. This is useful for validation or inspecting the required parameters before execution.

client.loadTool("get-toy-price").thenAccept(toolDef -> {
    System.out.println("Loaded Tool: " + toolDef.description());
    System.out.println("Parameters: " + toolDef.parameters());
});

Invoke a Tool

Invoking a tool sends a request to the MCP Server to execute the logic (SQL, API call, etc.). Arguments are passed as a Map<String, Object>.

import java.util.Map;

Map<String, Object> args = Map.of(
    "description", "plush dinosaur",
    "limit", 5
);

client.invokeTool("get-toy-price", args).thenAccept(result -> {
    // Pick the first item from the response.
    System.out.println("Result: " + result.content().get(0).text());
});

Authentication

Client to Server Authentication

This section describes how to authenticate the ToolboxClient itself when connecting to a MCP Toolbox server instance that requires authentication. This is crucial for securing your MCP Toolbox server endpoint, especially when deployed on platforms like Cloud Run, GKE, or any environment where unauthenticated access is restricted.

When is Client-to-Server Authentication Needed

You’ll need this if your MCP Toolbox server is configured to deny unauthenticated requests. For example:

• Your MCP Toolbox server is deployed on Google Cloud Run and configured to “Require authentication” (default).
• Your server is behind an Identity-Aware Proxy (IAP).
• You have custom authentication middleware.

Without proper client authentication, attempts to connect (like listTools) will fail with 401 Unauthorized or 403 Forbidden errors.

How it works

The Java SDK handles the generation of Authorization headers (Bearer tokens) using the Google Auth Library. It follows the Application Default Credentials (ADC) strategy to find the correct credentials based on the environment where your code is running.

Authenticating with Google Cloud Servers (Cloud Run)

For MCP Toolbox servers hosted on Google Cloud (e.g., Cloud Run), the SDK provides seamless OIDC authentication.

1. Configure Permissions

Grant the roles/run.invoker IAM role on the Cloud Run service to the principal calling the service.

• Local Dev: Grant this role to your User Account Email.
• Production: Grant this role to the Service Account attached to your application.

2. Configure Credentials

Option A: Local Development If running on your laptop, use the gcloud CLI to set up your user credentials.

gcloud auth application-default login

The SDK will automatically detect these credentials and generate an OIDC ID Token intended for your MCP Toolbox URL.

Option B: Google Cloud Environments When running within Google Cloud (e.g., Compute Engine, GKE, another Cloud Run service, Cloud Functions), ADC is configured automatically. The SDK uses the environment’s default service account. No extra code or configuration is required.

Option C: On-Premise / CI/CD If running outside of Google Cloud (e.g., Jenkins, AWS), create a Service Account Key (JSON) and set the environment variable:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

Authenticating the Tools

Tools can be configured within the MCP Toolbox service to require authentication, ensuring only authorized users or applications can invoke them, especially when accessing sensitive data.

When is Authentication Needed?

Authentication is configured per-tool within the MCP Toolbox service itself. If a tool you intend to use is marked as requiring authentication in the service, you must configure the SDK client to provide the necessary credentials (currently OAuth2 tokens) when invoking that specific tool.

Supported Authentication Mechanisms

The MCP Toolbox service enables secure tool usage through Authenticated Parameters. For detailed information on how these mechanisms work within the MCP Toolbox service and how to configure them, please refer to MCP Toolbox Service Documentation - Authenticated Parameters

Step 1: Configure Tools in MCP Toolbox Service

First, ensure the target tool(s) are configured correctly in the MCP Toolbox service to require authentication. Refer to the MCP Toolbox Service Documentation - Authenticated Parameters for instructions.

Step 2: Configure SDK Client

Your application needs a way to obtain the required token for the authenticated user. The SDK requires you to provide a function capable of retrieving this token when the tool is invoked.

Provide a Token Retriever Function

You must provide the SDK with an AuthTokenGetter (a function that returns a CompletableFuture<String>). This implementation depends on your application’s authentication flow (e.g., retrieving a stored token, initiating an OAuth flow).

import com.google.cloud.mcp.AuthTokenGetter;

// Define your token retrieval logic
AuthTokenGetter salesforceTokenGetter = () -> {
    return CompletableFuture.supplyAsync(() -> fetchTokenFromVault()); 
};
//example tool: search-salesforce and related sample params
client.loadTool("search-salesforce").thenCompose(tool -> {
    // Register the getter. It will be called every time 'execute' is run.
    tool.addAuthTokenGetter("salesforce_auth", salesforceTokenGetter);
    
    return tool.execute(Map.of("query", "recent leads"));
});

Complete Authentication Example

Here is a complete example of how to configure and invoke an authenticated tool.

import com.google.cloud.mcp.McpToolboxClient;
import com.google.cloud.mcp.AuthTokenGetter;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

public class AuthExample {
    public static void main(String[] args) {
        // 1. Define your token retrieval logic
        AuthTokenGetter tokenGetter = () -> {
            // Logic to retrieve ID token (e.g., from local storage, OAuth flow)
            return CompletableFuture.completedFuture("YOUR_ID_TOKEN"); 
        };

        // 2. Initialize the client
        McpToolboxClient client = McpToolboxClient.builder()
            .baseUrl("http://127.0.0.1:5000/mcp")
            .build();

        // 3. Load tool, attach auth, and execute
        client.loadTool("my-tool")
            .thenCompose(tool -> {
                // "my_auth" must match the name in the tool's authSources config
                tool.addAuthTokenGetter("my_auth", tokenGetter);
                
                return tool.execute(Map.of("input", "some input"));
            })
            .thenAccept(result -> {
                // Pick the first item from the response.
                System.out.println(result.content().get(0).text());
            })
            .join();
    }
}

Binding Parameter Values

The SDK allows you to pre-set, or “bind”, values for specific tool parameters before the tool is invoked or even passed to an LLM. These bound values are fixed and will not be requested or modified by the LLM during tool use.

Why Bind Parameters?

• Protecting sensitive information: API keys, secrets, etc.
• Enforcing consistency: Ensuring specific values for certain parameters.
• Pre-filling known data: Providing defaults or context.

Option A: Static Binding

Bind a fixed value to a tool object.

client.loadTool("get-toy-price").thenCompose(tool -> {
    // Bind 'currency' to 'USD' permanently for this tool instance
    tool.bindParam("currency", "USD");
    
    // Now invoke without specifying currency
    return tool.execute(Map.of("description", "lego set")); 
});

Option B: Dynamic Binding

Instead of a static value, you can bind a parameter to a synchronous or asynchronous function (Supplier). This function will be called each time the tool is invoked to dynamically determine the parameter’s value at runtime.

client.loadTool("check-order-status").thenCompose(tool -> {
    // Bind 'user_id' to a function that fetches the current user from context
    tool.bindParam("user_id", () -> SecurityContext.getCurrentUser().getId());
    
    // Invoke: The SDK will call the supplier to fill 'user_id'
    return tool.execute(Map.of("order_id", "12345"));
});

Error Handling

The SDK uses Java’s CompletableFuture API. Errors (Network issues, 4xx/5xx responses) are propagated as exceptions wrapped in CompletionException.

client.invokeTool("invalid-tool", Map.of())
    .handle((result, ex) -> {
        if (ex != null) {
            System.err.println("Invocation Failed: " + ex.getCause().getMessage());
            return null; // Handle error
        }
        return result; // Success path
    });