{"record":{"id":"ae2d69ea8918eddc","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-create-mcp-tools","errorCode":null,"errorMessage":"Failed to create MCP tools","messagePattern":"Failed to create MCP tools","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-sandbox/src/main/java/com/alibaba/cloud/ai/sandbox/ToolkitInit.java","lineNumber":424,"sourceCode":"\n        return converter.toBuiltinTools();\n    }\n\n    private static List<ToolCallback> buildMcpAgentTools(McpConfigConverter converter) {\n        try {\n            logger.info(\"Creating MCP tools from server configuration\");\n\n            List<MCPTool> mcpTools = converter.toBuiltinTools();\n            List<ToolCallback> agentTools = new ArrayList<>(mcpTools.size());\n            for (MCPTool mcpTool : mcpTools) {\n                agentTools.add(new SaaMCPTool(mcpTool).buildTool());\n            }\n\n            logger.info(\"Created {} MCP tools\", agentTools.size());\n            return agentTools;\n        } catch (Exception e) {\n            logger.error(\"Failed to create MCP tools: {}\", e.getMessage());\n            throw new RuntimeException(\"Failed to create MCP tools\", e);\n        }\n    }\n}\n","sourceCodeStart":406,"sourceCodeEnd":428,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-sandbox/src/main/java/com/alibaba/cloud/ai/sandbox/ToolkitInit.java#L406-L428","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the cause chain (e.getCause()) for the real failure (connection refused, timeout, protocol error).","Verify the MCP server is running and the configured endpoint/transport URL is correct.","Test connectivity to the MCP server (curl / ping the host:port).","Ensure MCP client config (timeouts, auth, command for stdio transport) matches the server."],"exampleFix":"// before\nMcpClient client = McpClient.builder().url(\"http://localhost:9999\")...\n// after\n// ensure server is up first, then correct URL\nMcpClient client = McpClient.builder().url(\"http://localhost:8080/mcp\")...\n","handlingStrategy":"try-catch","validationCode":"// before calling getMcpTools\nboolean reachable;\ntry (Socket s = new Socket()) {\n  s.connect(new InetSocketAddress(mcpHost, mcpPort), 3000);\n  reachable = true;\n} catch (IOException e) { reachable = false; }\nif (!reachable) throw new IllegalStateException(\"MCP server unreachable: \" + mcpHost);","typeGuard":null,"tryCatchPattern":"try {\n  List<Tool> tools = toolkitInit.getMcpTools();\n} catch (RuntimeException e) {\n  log.error(\"MCP tool creation failed\", e.getCause());\n  // degrade: proceed without MCP tools or retry after checking server\n}","preventionTips":["Start/verify the MCP sandbox server before initializing the toolkit.","Validate MCP endpoint and transport configuration at startup.","Add connection timeouts and health checks; log the full cause chain."],"tags":["mcp","tools","initialization"],"backgroundTag":"api-request-failed","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}