alibaba/spring-ai-alibaba · error · RuntimeException

Failed to create MCP tools

Error message

Failed to create MCP tools

What it means

ToolkitInit.buildMcpAgentTools catches any Exception raised while building MCP agent tools (MCP client connection, tool discovery, tool wrapping) and rethrows it as a RuntimeException with message 'Failed to create MCP tools'. The root cause is always in the wrapped exception.

Source

Thrown at spring-ai-alibaba-sandbox/src/main/java/com/alibaba/cloud/ai/sandbox/ToolkitInit.java:424

        return converter.toBuiltinTools();
    }

    private static List<ToolCallback> buildMcpAgentTools(McpConfigConverter converter) {
        try {
            logger.info("Creating MCP tools from server configuration");

            List<MCPTool> mcpTools = converter.toBuiltinTools();
            List<ToolCallback> agentTools = new ArrayList<>(mcpTools.size());
            for (MCPTool mcpTool : mcpTools) {
                agentTools.add(new SaaMCPTool(mcpTool).buildTool());
            }

            logger.info("Created {} MCP tools", agentTools.size());
            return agentTools;
        } catch (Exception e) {
            logger.error("Failed to create MCP tools: {}", e.getMessage());
            throw new RuntimeException("Failed to create MCP tools", e);
        }
    }
}

View on GitHub (pinned to f82da0b50f)

Solutions

  1. Inspect the cause chain (e.getCause()) for the real failure (connection refused, timeout, protocol error).
  2. Verify the MCP server is running and the configured endpoint/transport URL is correct.
  3. Test connectivity to the MCP server (curl / ping the host:port).
  4. Ensure MCP client config (timeouts, auth, command for stdio transport) matches the server.

Example fix

// before
McpClient client = McpClient.builder().url("http://localhost:9999")...
// after
// ensure server is up first, then correct URL
McpClient client = McpClient.builder().url("http://localhost:8080/mcp")...
Defensive patterns

Strategy: try-catch

Validate before calling

// before calling getMcpTools
boolean reachable;
try (Socket s = new Socket()) {
  s.connect(new InetSocketAddress(mcpHost, mcpPort), 3000);
  reachable = true;
} catch (IOException e) { reachable = false; }
if (!reachable) throw new IllegalStateException("MCP server unreachable: " + mcpHost);

Try / catch

try {
  List<Tool> tools = toolkitInit.getMcpTools();
} catch (RuntimeException e) {
  log.error("MCP tool creation failed", e.getCause());
  // degrade: proceed without MCP tools or retry after checking server
}

Prevention

When it happens

Trigger: Calling getMcpTools()/buildMcpAgentTools when the MCP server cannot be reached, initialization fails, tool listing throws, or tool conversion errors — any Exception in the try block.

Common situations: Sandbox/MCP server not running or wrong MCP endpoint config; network/firewall blocking the MCP connection; incompatible MCP server tool schema; missing timeout leading to connection errors.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/ae2d69ea8918eddc. Report an issue: GitHub.