feat!: transition Java SDK to MCP transport (#38)

* feat!: transition Java SDK to native MCP JSON-RPC transport

This PR updates the SDK to achieve transport parity with the Python, JS, and Go SDKs by seamlessly adopting the MCP standard and removing legacy REST mappings.

* Fix 405 error and debug test assertions

* Fix file formatting

* Refactor ToolResult text extraction and update tests

* Fix parsing of unauthorized error into ToolResult

* Fix string assertion in testRunToolWrongAuth

* Fix string assertion case sensitivity in auth test

* chore: format test file

* docs: update endpoint URLs to include /mcp path

* doc: Simplify urls in README

* fix(java): parse toolbox/authInvoke from _meta in list tools

* refactor: Remove `ToolResult.text()` helper method, update text content extraction to stream-based collection.

* chore: Revert /mcp auto-append and update docs to explicitly require /mcp

* docs: add release-please version annotations

* chore: revert example directory changes

* build: upgrade libraries-bom to 26.48.0 and google-auth-library to 1.23.0

* doc: Remove the optional step of deploying to a specific target

* doc: Revert to simplified README examples with comments

* doc: Improve README doc formatting and rendering and typos

Author: anubhav756

DEVELOPER.md

@@ -30,11 +30,6 @@ Commits](https://www.conventionalcommits.org/) for structuring commit messages.
     ```
 This will generate the package JAR in your local `.m2` repository, making it available for other local Maven projects.
 
-1. (Optional) Run deploy to a local directory for verification:
-   ```bash
-    mvn deploy -DaltDeploymentRepository=local::default::file://$(pwd)/target/staging-deploy
-    ```
-
 ## Release Process
 
 This repository uses [Release Please](https://github.com/googleapis/release-please) to automate the release process.

README.md

@@ -96,7 +96,7 @@ Add the dependency to your `pom.xml`:
 <dependency>
     <groupId>com.google.cloud.mcp</groupId>
     <artifactId>mcp-toolbox-sdk-java</artifactId>
-    <version>0.1.1</version>
+    <version>0.1.1</version> <!-- x-release-please-version -->
     <scope>compile</scope>
 </dependency>
 ```
@@ -106,21 +106,25 @@ Add the dependency to your `pom.xml`:
 ```
 dependencies {
     // Source: https://mvnrepository.com/artifact/com.google.cloud.mcp/mcp-toolbox-sdk-java
-    implementation("com.google.cloud.mcp:mcp-toolbox-sdk-java:0.1.1")
+    implementation("com.google.cloud.mcp:mcp-toolbox-sdk-java:0.1.1") // x-release-please-version
 }
 ```
 
 ## Usage
 
 ### Load the Client
 
-The McpToolboxClient is your entry point. It is thread-safe and designed to be instantiated once and reused.
+The `McpToolboxClient` is your entry point. It is thread-safe and designed to be instantiated once and reused.
 
-```
-import com.google.cloud.mcp.McpToolboxClient;
+```java
+// 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](https://my-toolbox-service.a.run.app)") 
+    .baseUrl("https://my-toolbox-service.a.run.app/mcp")
     // .apiKey("...") // Optional: Overrides automatic Google Auth
     .build();
 ```
@@ -162,7 +166,7 @@ client.loadTool("get-toy-price").thenAccept(toolDef -> {
 
 ### 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>.
+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>`.
 
 ```java
 import java.util.Map;
@@ -173,27 +177,30 @@ Map<String, Object> args = Map.of(
 );
 
 client.invokeTool("get-toy-price", args).thenAccept(result -> {
+    // Pick the first item from the response.
     System.out.println("Result: " + result.content().get(0).text());
+});
 ```
 
 ## Quickstart
 
 Here is the minimal code needed to connect to a toolbox and invoke a tool.
 
-```
+```java
 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](https://my-toolbox-service.a.run.app)") 
+            .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 -> {
@@ -205,14 +212,14 @@ public class App {
 }
 ```
 
-For a detailed example, check the ExampleUsage.java file in teh example folder of this repo.
+For a detailed example, check the ExampleUsage.java file in the example folder of this repo.
 
 > [!NOTE]
 >
-> The SDK is Async-First, using Java's CompletableFuture to bridge both patterns naturally.
-> - Asynchronous: Chain methods using .thenCompose(), .thenAccept(), and .exceptionally() > for non-blocking execution.
-> - If you prefer synchronous execution, simply call .join() on the result to block until > completion.
-```
+> The SDK is Async-First, using Java's `CompletableFuture` to bridge both patterns naturally.
+> - Asynchronous: Chain methods using `.thenCompose()`, `.thenAccept()`, and `.exceptionally()` for non-blocking execution.
+> - If you prefer synchronous execution, simply call `.join()` on the result to block until completion.
+```java
 // Async (Non-blocking)
 client.invokeTool("tool-name", args).thenAccept(result -> ...);
 // Sync (Blocking)
@@ -221,7 +228,7 @@ ToolResult result = client.invokeTool("tool-name", args).join();
 
 ## Authentication
 
-## Client to Server Authentication
+### Client to Server Authentication
 
 This section describes how to authenticate the `ToolboxClient` itself when connecting to a Toolbox server instance that requires authentication. This is crucial for securing your Toolbox server endpoint, especially when deployed on platforms like Cloud Run, GKE, or any environment where unauthenticated access is restricted.
 
@@ -241,7 +248,7 @@ The Java SDK handles the generation of **Authorization headers** (Bearer tokens)
 
 You need to set up [ADC](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment).
 
-### Authenticating with Google Cloud Servers (Cloud Run
+### Authenticating with Google Cloud Servers (Cloud Run)
 
 For Toolbox servers hosted on Google Cloud (e.g., Cloud Run), the SDK provides seamless OIDC authentication.
 
@@ -276,15 +283,14 @@ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
 | **Cloud Run** | Uses Service Account | **None.** (Automatic) |
 | **CI/CD** | Uses Service Account Key | Set GOOGLE\_APPLICATION\_CREDENTIALS=/path/to/key.json |
 
-*Note: If you provide an .apiKey() in the builder, it overrides the automatic ADC mechanism.*
+*Note: If you provide an `.apiKey()` in the builder, it overrides the automatic ADC mechanism.*
 
-## Authenticating the Tools
+### Authenticating the Tools
 
 Tools can be configured within the Toolbox service to require authentication, ensuring only authorized users or applications can invoke them, especially when accessing sensitive data.
 
-#### Warning
-
-Always use HTTPS to connect your application with the Toolbox service, especially in production environments or whenever the communication involves sensitive data (including scenarios where tools require authentication tokens). Using plain HTTP lacks encryption and exposes your application and data to significant security risks, such as eavesdropping and tampering.
+> [!WARNING]
+> Always use HTTPS to connect your application with the Toolbox service, especially in production environments or whenever the communication involves sensitive data (including scenarios where tools require authentication tokens). Using plain HTTP lacks encryption and exposes your application and data to significant security risks, such as eavesdropping and tampering.
 
 
 ### When is Authentication Needed?
@@ -309,7 +315,7 @@ You must provide the SDK with an `AuthTokenGetter` (a function that returns a `C
 
 **Important:** The **Service Name** (or Auth Source) used when adding the getter (e.g., `"salesforce_auth"`) must exactly match the name of the corresponding auth source defined in the tool's configuration.
 
-```
+```java
 import com.google.cloud.mcp.AuthTokenGetter;
 
 // Define your token retrieval logic
@@ -347,7 +353,7 @@ public class AuthExample {
 
         // 2. Initialize the client
         McpToolboxClient client = McpToolboxClient.builder()
-            .baseUrl("[http://127.0.0.1:5000](http://127.0.0.1:5000)")
+            .baseUrl("http://127.0.0.1:5000/mcp")
             .build();
 
         // 3. Load tool, attach auth, and execute
@@ -359,6 +365,7 @@ public class AuthExample {
                 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();
@@ -376,19 +383,17 @@ The SDK allows you to pre-set, or "bind", values for specific tool parameters be
 * Enforcing consistency: Ensuring specific values for certain parameters.  
 * Pre-filling known data: Providing defaults or context.
 
-##### Important
-
-The parameter names used for binding (e.g., `"api_key"`) must exactly match the parameter names defined in the tool's configuration within the Toolbox service.
-
-##### Note
+> [!IMPORTANT]
+> The parameter names used for binding (e.g., `"api_key"`) must exactly match the parameter names defined in the tool's configuration within the Toolbox service.
 
-You do not need to modify the tool's configuration in the Toolbox service to bind parameter values using the SDK.
+> [!NOTE]
+> You do not need to modify the tool's configuration in the Toolbox service to bind parameter values using the SDK.
 
 ### Option A: Static Binding
 
 Bind a fixed value to a tool object.
 
-```
+```java
 client.loadTool("get-toy-price").thenCompose(tool -> {
     // Bind 'currency' to 'USD' permanently for this tool instance
     tool.bindParam("currency", "USD");
@@ -402,7 +407,7 @@ client.loadTool("get-toy-price").thenCompose(tool -> {
 
 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.
 
-```
+```java
 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());
@@ -412,15 +417,15 @@ client.loadTool("check-order-status").thenCompose(tool -> {
 });
 ```
 
-##### Important
-
-You don't need to modify tool configurations to bind parameter values.
+> [!IMPORTANT]
+>
+> You don't need to modify tool configurations to bind parameter values.
 
 ## Error Handling
 
-The SDK uses Java's CompletableFuture API. Errors (Network issues, 4xx/5xx responses) are propagated as exceptions wrapped in CompletionException.
+The SDK uses Java's `CompletableFuture` API. Errors (Network issues, 4xx/5xx responses) are propagated as exceptions wrapped in `CompletionException`.
 
-```
+```java
 
 client.invokeTool("invalid-tool", Map.of())
     .handle((result, ex) -> {
@@ -435,8 +440,8 @@ client.invokeTool("invalid-tool", Map.of())
 
 ## Contributing
 
-We welcome contributions\! Please see [CONTRIBUTING.md](https://www.google.com/search?q=CONTRIBUTING.md) for details on how to submit pull requests, report bugs, or request features.
+We welcome contributions\! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to submit pull requests, report bugs, or request features.
 
 ## License
 
-This project is licensed under the Apache 2.0 License \- see the [LICENSE](https://www.google.com/search?q=LICENSE) file for details.
+This project is licensed under the Apache 2.0 License \- see the [LICENSE](https://github.com/googleapis/mcp-toolbox-sdk-java/blob/main/LICENSE) file for details.

demo-applications/cymbal-transit/README.md

@@ -120,6 +120,6 @@ or
 To directly deploy your agent to Cloud Run and test there:
 
 ``` bash
-gcloud run deploy cymbal-transit --source . --set-env-vars GCP_PROJECT_ID=<<YOUR_PROJECT_ID>>,GCP_REGION=us-central1,GEMINI_MODEL_NAME=gemini-2.5-flash,MCP_TOOLBOX_URL=<<YOUR_MCP_TOOLBOX_URL>> --allow-unauthenticated
+gcloud run deploy cymbal-transit --source . --set-env-vars GCP_PROJECT_ID=<<YOUR_PROJECT_ID>>,GCP_REGION=us-central1,GEMINI_MODEL_NAME=gemini-2.5-flash,MCP_TOOLBOX_URL=<<YOUR_MCP_TOOLBOX_URL_ENDING_IN_/mcp>> --allow-unauthenticated
 ```
-Replace the placeholder variables enclosed within <<>>.
+Replace the placeholder variables enclosed within <<>>. Ensure that your `MCP_TOOLBOX_URL` explicitly ends with `/mcp` (e.g., `https://my-toolbox-service.a.run.app/mcp`).

demo-applications/cymbal-transit/src/main/java/cloudcode/cymbal/web/CymbalTransitController.java

@@ -189,7 +189,7 @@ public void init() {
     public CompletableFuture<String> findAllSchedules() {
         return mcpClient.invokeTool("find-bus-schedules", Collections.emptyMap()).thenApply(result -> {
             if (result.isError() || result.content() == null || result.content().isEmpty()) return "No schedules found.";
-            return result.content().get(0).text();
+            return getTextContent(result);
         });
     }
 
@@ -201,7 +201,7 @@ public CompletableFuture<String> querySchedules(String origin, String destinatio
         return mcpClient.invokeTool("query-schedules", params).thenApply(result -> {
             if (result.isError() || result.content() == null || result.content().isEmpty()) return "No specific schedules found.";
             System.out.println(result);
-            return result.content().get(0).text();
+            return getTextContent(result);
         });
     }
 
@@ -214,17 +214,26 @@ public CompletableFuture<String> bookTicket(String tripId, String passengerName)
             })
             .thenApply(result -> {
                 if (result.isError() || result.content() == null || result.content().isEmpty()) return "Transaction failed.";
-                return result.content().get(0).text();
+                    return getTextContent(result);
             });
     }
 
     public CompletableFuture<String> searchPolicies(String searchQuery) {
         return mcpClient.invokeTool("search-policies", Map.of("search_query", searchQuery))
             .thenApply(result -> {
                 if (result.isError() || result.content() == null || result.content().isEmpty()) return "No policy information found.";
-                return result.content().get(0).text();
+                    return getTextContent(result);
             });
     }
+
+    private String getTextContent(com.google.cloud.mcp.ToolResult result) {
+        if (result.content() == null)
+            return "";
+        return result.content().stream()
+                .filter(c -> "text".equals(c.type()) && c.text() != null)
+                .map(c -> c.text())
+                .collect(java.util.stream.Collectors.joining("\n"));
+    }
 }
 
 /**

example/README.md

@@ -4,9 +4,9 @@ These sample Java files allow you to test the features supported in the Java ver
 
 1. First set up database (AlloyDB in this case) and ingest data for the tools referenced in this example. In order to demonstrate the use of tools across applications, we have considered a RETAIL STORE and TOY STORE application data together. In order to install cluster, instance and setup data, for this sample use case, follow the first 4 steps of the first codelab (hybrid search) and the 5th step of the second codelab (toystore app) below:
 
-   [https://codelabs.developers.google.com/hybrid-search-on-cloudrun](url)
+   https://codelabs.developers.google.com/hybrid-search-on-cloudrun
    and
-   [https://codelabs.developers.google.com/toy-store-app](url)
+   https://codelabs.developers.google.com/toy-store-app
 
 2. To start with tools, go ahead and create the MCP Toolbox Server for the sameple use case we are looking at.
 
@@ -45,7 +45,7 @@ In any case remember to change the `YOUR_TOOLBOX_SERVICE_ENDPOINT` placeholder i
    <dependency>
      <groupId>com.google.cloud.mcp</groupId>
      <artifactId>mcp-toolbox-sdk-java</artifactId>
-     <version>0.1.1</version>
+     <version>0.1.1</version> <!-- x-release-please-version -->
    </dependency>
    ```
 

example/src/main/java/cloudcode/helloworld/ExampleUsage.java

@@ -101,7 +101,7 @@ public static void main(String[] args) {
                     return client.invokeTool("get-retail-facet-filters", Map.of());
                 })
                 .thenCompose(result -> {
-                    System.out.println("    -> Result: " + (result.content() != null ? "Received Data" : "Empty"));
+                        System.out.println("    -> Result: " + (result.content() != null ? "Received Data" : "Empty"));
 
                     // STEP 3: INVOKE TOOL WITH AUTHENTICATED PARAMETERS
                     System.out.println("\n[5] Testing Authenticated Tool: 'get-toy-price'...");
@@ -121,7 +121,8 @@ public static void main(String[] args) {
                     return tool.execute(Map.of("description", "barbie"))
                         .thenCompose(result1 -> {
                             if (result1.content() != null && !result1.content().isEmpty()) {
-                                System.out.println("    -> Result (Unbound): " + result1.content().get(0).text());
+                                        System.out
+                                                .println("    -> Result (Unbound): " + result1.content().get(0).text());
                             }
 
                             // NOW bind the parameter
@@ -136,9 +137,9 @@ public static void main(String[] args) {
                 .thenAccept(result -> {
                     System.out.println("\n[6] Final Result (Bound):");
                     if (result.isError()) {
-                        System.err.println("Tool execution failed: " + result.content().get(0).text());
+                            System.err.println("Tool execution failed: " + result.content().get(0).text());
                     } else if (result.content() != null && !result.content().isEmpty()) {
-                        String output = result.content().get(0).text();
+                            String output = result.content().get(0).text();
                         System.out.println("    " + output.substring(0, Math.min(output.length(), 200)) + "...");
                     } else {
                         System.out.println("    Empty Response");

pom.xml

@@ -67,14 +67,14 @@
             <dependency>
                 <groupId>com.google.cloud</groupId>
                 <artifactId>libraries-bom</artifactId>
-                <version>26.32.0</version>
+                <version>26.48.0</version>
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
             <dependency>
                 <groupId>com.google.errorprone</groupId>
                 <artifactId>error_prone_annotations</artifactId>
-                <version>2.21.1</version>
+                <version>2.30.0</version>
             </dependency>
         </dependencies>
     </dependencyManagement>
@@ -91,6 +91,7 @@
         <dependency>
             <groupId>com.google.auth</groupId>
             <artifactId>google-auth-library-oauth2-http</artifactId>
+            <version>${google.auth.version}</version>
         </dependency>
 
         <!-- Testing -->