alibaba/spring-ai-alibaba · error · BizException

CreateMCPServerError

CreateMCPServerError

Error message

Failed to create MCPServer. fail parse InstallConfig

What it means

Thrown by McpServerServiceImpl.createMcp when any exception occurs while persisting/processing a new MCP server — in particular when the install/deploy config (InstallConfig) cannot be parsed or validated. The original exception is attached as cause.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/base/service/impl/McpServerServiceImpl.java:121

				throw new Exception(String.valueOf(checkResult.getMessage()));
			}
			entity.setDeployConfig(checkResult.getData());
			entity.setHost(fetchHost(checkResult.getData()));
			entity.setDetailConfig(detail.getDetailConfig());
			entity.setDescription(detail.getDescription());
			entity.setWorkspaceId(context.getWorkspaceId());
			entity.setAccountId(context.getAccountId());
			entity.setStatus(McpServerStatusEnum.Normal.getCode());
			entity.setBizType(detail.getBizType());
			entity.setInstallType(detail.getInstallType());
			entity.setDeployEnv(detail.getDeployEnv());
			entity.setSource(detail.getSource());
			entity.setType(detail.getType() == null ? McpServerTypeEnum.CUSTOMER.name() : detail.getType());
			this.save(entity);
			return serverCode;
		}
		catch (Exception e) {
			throw new BizException(ErrorCode.CREATE_MCP_ERROR.toError("fail parse InstallConfig"), e);
		}

	}

	/**
	 * Updates an existing MCP server configuration
	 * @param detail Updated server configuration
	 */
	@Override
	public void updateMcp(McpServerDetail detail) {
		try {
			RequestContext context = RequestContextHolder.getRequestContext();
			String serverCode = detail.getServerCode();
			McpServerEntity entity = getMcpByCode(context.getWorkspaceId(), serverCode, null);
			if (entity == null) {
				throw new BizException(MCP_NOT_FOUND.toError());
			}
			entity.setName(detail.getName());

View on GitHub (pinned to f82da0b50f)

Solutions

1. Inspect the cause exception in server logs to see the exact parse/validation failure.
2. Validate the installConfig JSON against the expected InstallConfig schema (correct fields for stdio vs sse type) before calling createMcp.
3. Check installType is a supported value and matches the deployConfig format; correct and retry.

Example fix

// before: malformed install config
{"installType": "stdio"}  // missing command/args
// after
{"installType": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"]}

if (detail.getInstallConfig() == null) throw new IllegalArgumentException("installConfig required");
// pre-validate with the same manager used server-side
Result<String> check = mcpManager.processInstallConfig(detail.getDeployConfig(), detail.getInstallType());
if (!check.isSuccess()) throw new IllegalArgumentException("Invalid InstallConfig: " + check.getMessage());

try {
    mcpService.createMcp(detail);
} catch (BizException e) {
    if ("CreateMCPServerError".equals(e.getCode())) {
        log.error("MCP create failed", e.getCause()); // inspect cause for parse error
    } else { throw e; }
}

When it happens

Trigger: Calling createMcp with a detail whose installConfig/deployConfig is malformed JSON, has an unknown installType, or fails mcpManager.processInstallConfig validation, causing the catch-all to wrap the failure.

Common situations: Hand-crafted MCP server payloads with invalid command/URL fields, JSON that does not match the InstallConfig schema, new install types not supported by the deployed manager version.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• UpdateMCPServerError
• Nacos config content is not valid JSON, but dot notation was
• MissingParameter
• MCPServerNotFound
• DeleteMCPServerError

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