alibaba/spring-ai-alibaba · error · IllegalArgumentException

MCP Server [${serverCode}] not found!

Error message

MCP Server [${serverCode}] not found!

What it means

MCPNodeSection.render looks up the MCP server entity by workspaceId and the node's serverCode. If no matching McpServerEntity exists, render throws IllegalArgumentException naming the missing server code.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/generator/service/generator/workflow/sections/MCPNodeSection.java:63

	@Override
	public boolean support(NodeType nodeType) {
		return NodeType.MCP.equals(nodeType);
	}

	@Override
	public String render(Node node, String varName) {
		if (this.mcpServerService == null) {
			throw new IllegalArgumentException(
					"The current mode does not support Studio's MCP node code generation. Please start the complete StudioApplication class");
		}
		MCPNodeData nodeData = (MCPNodeData) node.getData();

		RequestContext context = RequestContextHolder.getRequestContext();
		McpServerEntity mcpServerEntity = mcpServerService.getMcpByCode(context.getWorkspaceId(),
				nodeData.getServerCode(), null);
		if (mcpServerEntity == null) {
			throw new IllegalArgumentException("MCP Server [" + nodeData.getServerCode() + "] not found!");
		}

		McpServerDeployConfig deployConfig = JsonUtils.fromJson(mcpServerEntity.getDeployConfig(),
				McpServerDeployConfig.class);
		String endPoint = deployConfig.getRemoteEndpoint();
		String baseUri = deployConfig.getRemoteAddress();

		return String.format("""
				// -- MCP Node [%s] --
				stateGraph.addNode("%s", AsyncNodeAction.node_async(
				    createMcpNodeAction(%s, %s, %s, %s, %s, %s)
				));

				""", nodeData.getServerName(), varName, ObjectToCodeUtil.toCode(baseUri),
				ObjectToCodeUtil.toCode(endPoint), ObjectToCodeUtil.toCode(nodeData.getToolName()),
				ObjectToCodeUtil.toCode(nodeData.getInputJsonTemplate()),
				ObjectToCodeUtil.toCode(nodeData.getInputKeys()), ObjectToCodeUtil.toCode(nodeData.getOutputKey()));
	}

View on GitHub (pinned to f82da0b50f)

Solutions

  1. Create or re-register the MCP server with the referenced code in the same workspace
  2. Fix the serverCode on the MCP node data to match an existing server
  3. Switch the workspace context to the one containing the MCP server

Example fix

// before
"serverCode": "weather_tool" // not registered
// after
"serverCode": "amap-weather" // registered in this workspace
Defensive patterns

Strategy: validation

Validate before calling

boolean exists = mcpServerService.getMcpByCode(workspaceId, nodeData.getServerCode(), null) != null; if (!exists) { throw new IllegalArgumentException("Referenced MCP server missing: " + nodeData.getServerCode()); }

Type guard

null

Try / catch

try { section.render(node, varName); } catch (IllegalArgumentException e) { log.error("{} — re-register the MCP server or fix serverCode", e.getMessage()); }

Prevention

When it happens

Trigger: An MCP node references serverCode X, but getMcpByCode(workspaceId, X, null) returns null — the server is not registered in the workspace's MCP server store.

Common situations: Server deleted or renamed in Studio after the workflow referenced it; copying workflows across workspaces where the MCP server doesn't exist; typo in serverCode in the DSL.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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