Package com.tnsai.mcp.hub

Class McpToolBridge

java.lang.Object
com.tnsai.mcp.hub.McpTool
com.tnsai.mcp.hub.McpToolBridge
All Implemented Interfaces:
AutoCloseable
public class McpToolBridge extends McpTool
Dynamic bridge that wraps any MCP server and exposes all its tools.

Unlike extending McpTool for specific tools, this class provides a generic bridge to any MCP server, automatically discovering and exposing all available tools.

Usage Examples

Wrap filesystem MCP server


 McpToolBridge bridge = McpToolBridge.stdio(
     "npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"
 );

 bridge.connect();

 // Discover available tools
 System.out.println("Available tools: " + bridge.getToolNames());

 // Call any tool
 String result = bridge.call("read_file", Map.of("path", "/tmp/test.txt"));

Wrap HTTP-based MCP server


 McpToolBridge bridge = McpToolBridge.http("https://mcp.example.com/sse");

 bridge.connect();

 // Get tool schema
 McpToolDefinition searchTool = bridge.getTool("search");
 System.out.println("Search schema: " + searchTool.getInputSchema());

 // Execute tool
 String result = bridge.call("search", Map.of("query", "hello world"));

Use with TnsAI agents


 // Create bridge
 McpToolBridge bridge = McpToolBridge.stdio("npx", "-y", "@mcp/server");

 // Convert to TnsAI tools
 List<com.tnsai.annotations.Tool> tnsaiTools = bridge.toTnsAITools();

 // Register with agent
 agent.registerTools(tnsaiTools);

  • Method Details

    • stdio

      public static McpToolBridge stdio(String... command)
      Create a bridge with stdio transport.
      Parameters:
      command - the command to start the MCP server
      Returns:
      a new McpToolBridge

    • http

      public static McpToolBridge http(String serverUrl)
      Create a bridge with HTTP/SSE transport.
      Parameters:
      serverUrl - the MCP server URL
      Returns:
      a new McpToolBridge

    • http

      public static McpToolBridge http(String serverUrl, Map<String,String> headers)
      Create a bridge with HTTP/SSE transport and custom headers.
      Parameters:
      serverUrl - the MCP server URL
      headers - custom headers (e.g., authentication)
      Returns:
      a new McpToolBridge

    • httpWithApiKey

      public static McpToolBridge httpWithApiKey(String serverUrl, String apiKey)
      Create a bridge with HTTP/SSE transport and API key authentication.
      Parameters:
      serverUrl - the MCP server URL
      apiKey - API key for Bearer authentication
      Returns:
      a new McpToolBridge

    • custom

      public static McpToolBridge custom(McpTransport transport, String name, String description)
      Create a bridge with custom transport.
      Parameters:
      transport - the transport to use
      name - the bridge name
      description - the bridge description
      Returns:
      a new McpToolBridge

    • call

      public String call(String toolName, Map<String,Object> arguments)
      Call a tool on the MCP server.
      Parameters:
      toolName - the tool name
      arguments - the tool arguments
      Returns:
      the result string

    • call

      public String call(String toolName)
      Call a tool with no arguments.

    • call

      public String call(String toolName, String argName, Object argValue)
      Call a tool with a single argument.

    • getName

      public String getName()
      Get the bridge name.

    • getDescription

      public String getDescription()
      Get the bridge description.

    • getToolsDescription

      public String getToolsDescription()
      Get a formatted list of all available tools.

    • toTnsAITools

      public List<com.tnsai.tools.method.DynamicToolMethod> toTnsAITools()
      Convert MCP tools to TnsAI tool definitions.

      Creates wrapper tools that can be registered with TnsAI agents. Each MCP tool becomes a separate TnsAI tool.

      Returns:
      list of TnsAI-compatible tools

    • toDynamicToolMethod

      public com.tnsai.tools.method.DynamicToolMethod toDynamicToolMethod(McpToolDefinition mcpTool)
      Build a DynamicToolMethod fronting a single MCP tool discovered through this bridge. Use directly when the consumer already has a specific MCP tool definition in hand, otherwise prefer toTnsAITools().

      The MCP 2025-03-26 tool annotations (McpToolDefinition.getAnnotations()) are mapped onto the corresponding TnsAI tool hints (TNS-641):

      MCP annotation → TnsAI hint
      MCP annotationTnsAI hintEffect
      destructiveHint = true requiresConfirmation = true brings the tool under the AGENT-V006 approval gate (TNS-556) — a destructive MCP tool registered without a ToolCallFilter now raises the safety warning instead of dispatching unattended
      idempotentHint = true idempotent = true informs the retry / fallback layer
      Both default to false when the annotation is absent (the MCP-conservative reading). readOnlyHint / openWorldHint are not mapped — their natural TnsAI counterpart is sideEffect, which is not yet modelled on DynamicToolMethod (deferred in TNS-556 until a runtime consumer reads it).
      Since:
      0.7.0 (replaced the TnsAIToolWrapper implements Tool adapter that retired with the Tool interface); MCP-annotation → safety-hint mapping added in 0.11.1 (TNS-641)