MCP Toolbox Java SDKCore实战指南在 Java 应用中加载、认证并调用数据库与 API 工具【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox导读MCP ToolboxMCP Toolbox for Databases是一个基于 Model Context ProtocolMCP构建的开源数据库工具服务端它将数据库查询、API 连接器等能力统一封装为可被 GenAI 应用调用的工具。本文围绕 Java SDK 的 Core 包展开讲解如何用McpToolboxClient在自己的 Java 应用中完成工具集加载、工具定义获取、工具调用、两阶段认证客户端认证与工具级认证以及参数绑定并借助仓库源码服务端 API 路由、参数解析实现、工具 Manifest 定义解释其背后的真实调用链让读者既能照抄代码快速接入也能理解 SDK 与服务端的交互原理。概览Java SDK 与服务端的分工Java SDK 是 MCP Toolbox 服务端的官方客户端之一Python、JavaScript/TypeScript、Go SDK 见 connect-to 总览。它并不替代服务端而是充当客户端代理负责从运行中的 MCP Toolbox 实例拉取工具定义tool definition将工具表示为便捷的 Java 对象或函数调用工具触发服务端执行底层配置好的 SQL、API 调用等逻辑按需处理认证与参数绑定。从仓库源码看服务端通过/api前缀的 REST 路由向 SDK 暴露能力internal/server/api.gor.Get(/toolset, func(w http.ResponseWriter, r *http.Request) { toolsetHandler(s, w, r) }) r.Get(/toolset/{toolsetName}, func(w http.ResponseWriter, r *http.Request) { toolsetHandler(s, w, r) }) r.Route(/tool/{toolName}, func(r chi.Router) { r.Get(/, func(w http.ResponseWriter, r *http.Request) { toolGetHandler(s, w, r) }) r.Post(/invoke, func(w http.ResponseWriter, r *http.Request) { toolInvokeHandler(s, w, r) }) })Java SDK 的loadToolset()、loadTool()、invokeTool()正是分别对应这些路由返回的工具定义在服务端被称为 Manifest源码注释明确写着Manifest is the representation of tools sent to Client SDKsinternal/tools/tools.go。安装Java SDKCore 包以com.google.cloud.mcp:mcp-toolbox-sdk-java的坐标发布在 Maven Central Repository支持 Maven 与 Gradle 两种方式接入版本号请以 Maven Central 上该坐标的最新发布版本为准。Maven在pom.xml中添加依赖dependency groupIdcom.google.cloud.mcp/groupId artifactIdmcp-toolbox-sdk-java/artifactId !-- Replace VERSION with the latest version -- versionVERSION/version scopecompile/scope /dependencyGradle在build.gradle的 dependencies 中声明dependencies { // Replace VERSION with the latest version implementation(com.google.cloud.mcp:mcp-toolbox-sdk-java:VERSION) }前置条件请先确保 MCP Toolbox Server 已经完成配置并运行本地或 Cloud Run 部署均可接入方式与部署细节可参考 配置文档 与 getting-started 文档。快速开始最小可用代码下面是最小化的连接代码——创建客户端、调用一个工具并打印结果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 } }要点说明baseUrl指向服务端的 MCP 端点通常形如http://localhost:5000/mcp本地或https://service.a.run.app/mcpCloud Run调用参数以MapString, Object传入对应工具在服务端配置中的参数名result.content().get(0).text()取响应内容中的第一条文本结果MCP 标准 Content 结构。SDK 完整示例包含更多调用方式的ExampleUsage.java位于 Java SDK 仓库的example/src/main/java/cloudcode/helloworld/目录下可与本文代码互相印证。Async-First 设计同步与异步两种写法SDK 是异步优先Async-First设计的全程基于 Java 的CompletableFuture天然桥接异步与同步两种模式异步非阻塞使用.thenCompose()、.thenAccept()、.exceptionally()链式编排同步阻塞在链尾调用.join()阻塞直到执行完成。// Async (Non-blocking) client.invokeTool(tool-name, args).thenAccept(result - ...); // Sync (Blocking) ToolResult result client.invokeTool(tool-name, args).join();使用详解加载客户端McpToolboxClient是整个 SDK 的入口对象它是线程安全的官方推荐只实例化一次并复用// 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();baseUrl的末尾/mcp是 MCP Toolbox 服务端暴露 MCP 端点的固定路径若服务端开启了访问控制可在 builder 中显式传入.apiKey(...)它会覆盖下述的自动 Google 认证机制。加载工具集Toolset工具集是服务端对工具的分组管理概念对应服务端的 group 机制。loadToolset()不带参数时等价于listTools返回全部工具的定义 Map传入工具集名称则只加载该子集// 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()); });服务端视角工具集信息由toolsetHandler通过PrimitiveMgr.GetGroup(toolsetName)查找分组再生成ToolsetManifest返回internal/server/api.goGET /api/toolset/{toolsetName}即对应此逻辑。加载单个工具如果你已经明确要使用某个具体工具可以直接加载其定义用于调用前的参数校验或查看必填参数client.loadTool(get-toy-price).thenAccept(toolDef - { System.out.println(Loaded Tool: toolDef.description()); System.out.println(Parameters: toolDef.parameters()); });服务端视角toolGetHandler查找工具后返回ToolsManifest以工具名为键的 Manifest 映射internal/server/api.go。Manifest 中的Parameters字段[]parameters.ParameterManifestinternal/tools/tools.go正是 SDK 打印出的参数定义来源。调用工具invokeTool会向 MCP Server 发送执行请求由服务端执行具体逻辑SQL、API 调用等。参数以MapString, Object传入import java.util.Map; MapString, 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()); });服务端视角POST /api/tool/{toolName}/invoke的处理流程是完整的一整套管线internal/server/api.go校验工具与数据源Source存在且有效提取Authorization头中的访问令牌tools.AccessToken检查该工具是否需要客户端级授权RequiresClientAuthorization需要但缺少令牌则返回401遍历已配置的 Auth Service从请求头解析 claims执行工具级授权检查tool.Authorized用parameters.ParseParams解析请求体参数含认证参数解析见下文调用tool.EmbedParams做参数嵌入最后tool.Invoke真正执行。认证两阶段模型MCP Toolbox 的认证分为两个层次客户端到服务器的认证你的应用访问 Toolbox 端点本身与工具级认证个别工具要求携带用户级 OAuth2 令牌才能执行。SDK 对两者都有内置支持。第一阶段客户端到服务器认证当服务端被配置为拒绝匿名请求时例如 Cloud Run 默认的Require authentication、IAP 代理或自定义认证中间件客户端必须提供有效的凭据否则像listTools之类的操作会返回401 Unauthorized或403 Forbidden。工作原理Java SDK 借助 Google Auth Library 生成AuthorizationBearer token请求头并遵循Application Default CredentialsADC策略根据代码运行环境自动寻找凭据。本地开发需要先配置 ADC可通过gcloud完成。针对 Google Cloud 服务端Cloud Run的认证1. 配置权限在 Cloud Run 服务上为调用方授予roles/run.invokerIAM 角色本地开发授予你的用户账号邮箱生产环境授予应用所挂载的服务账号。2. 配置凭据按运行环境三选一Option A本地开发——在笔记本上使用gcloudCLI 登录用户凭据gcloud auth application-default loginSDK 会自动检测这些凭据并为你的 MCP Toolbox URL 生成 OIDC ID Token。Option BGoogle Cloud 环境——在 Compute Engine、GKE、另一个 Cloud Run 服务、Cloud Functions 等环境内运行时ADC 自动配置完成SDK 直接使用环境的默认服务账号无需任何额外代码或配置。Option C本地机房 / CI/CD——在 Google Cloud 之外如 Jenkins、AWS运行时创建服务账号密钥JSON并设置环境变量export GOOGLE_APPLICATION_CREDENTIALS/path/to/key.json环境凭据机制需要做的配置本地开发用户凭据运行gcloud auth application-default loginCloud Run服务账号无需配置自动CI/CD服务账号密钥设置GOOGLE_APPLICATION_CREDENTIALS/path/to/key.json注意如果在 builder 中提供了.apiKey()它将覆盖上述自动 ADC 机制。第二阶段工具级认证服务端可以为单个工具配置要求认证只有授权用户或应用才能调用涉及敏感数据的工具。此时 SDK 客户端必须在该工具被调用时提供对应凭据当前为 OAuth2 令牌。何时需要认证是按工具在服务端配置的。如果目标工具在服务端被标记为需要认证就必须通过 SDK 为它配置凭据提供器。配置方法Authenticated Parameters 机制详见 工具配置文档。Step 1在服务端配置工具确保目标工具在 MCP Toolbox 服务中已正确配置为需要认证authenticated parameters。Step 2配置 SDK 客户端应用需要一个能拿到当前用户令牌的途径。SDK 要求提供一个令牌获取器——AuthTokenGetter它是一个返回CompletableFutureString的函数具体实现取决于你的应用认证流程例如读取已存令牌、发起 OAuth 流程。提供令牌获取函数注意添加 getter 时使用的服务名Auth Source如salesforce_auth必须与工具配置中定义的 auth source 名称完全一致。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)); });提示令牌获取函数在每次工具调用需要认证参数时都会被调用。如果令牌有效期较长或获取过程较消耗资源建议在函数内部实现缓存逻辑避免重复获取或生成。完整认证示例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 tools authSource 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(); } }服务端源码印证工具级认证在服务端落地于两处——参数解析带认证服务的参数由parseFromAuthService从 claims 中取值若对应 auth service 的 claims 缺失或无效会返回401错误internal/util/parameters/parameters.go。各类型参数String/Int/Float/Boolean/Array/Map均支持WithXxxAuth选项挂载AuthServices并会在 Manifest 中仅暴露服务名列表internal/util/parameters/parameters.go授权校验toolInvokeHandler在真正执行前会比对已验证的 auth services与工具要求的 auth sourcestool.Authorized不匹配则返回401internal/server/api.go。安全提醒请始终使用HTTPS连接应用与 MCP Toolbox 服务尤其是在生产环境或涉及敏感数据包括工具需要认证令牌的场景时。明文 HTTP 缺乏加密会使应用和数据暴露于窃听、篡改等重大安全风险中。绑定参数值Parameter BindingSDK 允许在工具被调用甚至被传给 LLM之前为特定参数**预绑定bind**值。被绑定的值是固定的LLM 在工具使用过程中不会请求或修改这些值。为什么要绑定参数保护敏感信息API Key、密钥等强制一致性确保某些参数始终为指定值预填已知数据提供默认值或上下文。注意绑定时使用的参数名如api_key必须与工具在 MCP Toolbox 服务中配置的参数名完全一致。提示使用 SDK 绑定参数无需修改服务端的工具配置。方式 A静态绑定将固定值绑定到工具对象上该工具实例后续调用都会携带此值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)); });方式 B动态绑定除了静态值还可以把参数绑定到同步或异步函数Supplier上。该函数会在每次工具调用时执行动态决定参数在运行时的值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)); });动态绑定非常适合从当前安全上下文取用户身份从密钥库取令牌这类随调用而变化的值且同样不需要改动服务端配置。错误处理SDK 基于CompletableFutureAPI网络问题、4xx/5xx响应等错误会以异常形式传播并被包装在CompletionException中。推荐用.handle()同时处理成功与失败两条路径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 });与此对应服务端在调用失败时会区分错误类别Agent 类错误业务校验失败以 200 返回错误信息Server 类错误则按具体状态码返回401/403透传其余默认500未知错误统一500internal/server/api.go。理解这一分类有助于在客户端精准解析异常根因。总结接入路线图部署服务端完成 MCP Toolbox Server 的配置与运行本地或 Cloud Run引入 SDK按 Maven/Gradle 坐标com.google.cloud.mcp:mcp-toolbox-sdk-java添加依赖创建客户端McpToolboxClient.builder().baseUrl(...).build()单例复用加载并调用loadToolset()/loadTool()获取工具定义invokeTool()或tool.execute()执行配置认证按运行环境完成 ADC 配置客户端认证对受保护工具注册AuthTokenGetter工具级认证绑定与容错用静态/动态绑定隐藏敏感参数与上下文数据用.handle()/.exceptionally()处理异步错误。这套链路与仓库中的服务端实现internal/server/api.go、internal/util/parameters/parameters.go、internal/tools/tools.go一一对应读者既可以在数分钟内完成 Java 应用接入也可以顺着上述文件深入理解 MCP Toolbox 的工具管理、参数解析与认证授权机制。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考