What causes "parameters `mcpName` can't be empty or null" in alibaba/nacos?

Set McpServerEndpointRequest.mcpName to the target MCP server's name before sending.

alibaba/nacos · warning · NacosApiException

PARAMETER_MISSING

PARAMETER_MISSING

Error message

parameters `mcpName` can't be empty or null

What it means

Thrown by McpServerEndpointRequestHandler.checkParameters() when the gRPC McpServerEndpointRequest.mcpName is blank. The handler validates mcpName before looking up the server. Because handle() wraps the call in try/catch(NacosException), the exception is not propagated to the gRPC transport; it is placed into the McpServerEndpointResponse via setErrorInfo and returned as a normal response carrying the error code and message.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/remote/handler/McpServerEndpointRequestHandler.java:104

    @ExtractorManager.Extractor(rpcExtractor = McpServerRequestParamExtractor.class)
    @Secured(action = ActionTypes.WRITE, signType = SignType.AI)
    public McpServerEndpointResponse handle(McpServerEndpointRequest request, RequestMeta meta)
        throws NacosException {
        McpRequestUtil.fillNamespaceId(request);
        try {
            checkParameters(request);
            Instance instance = buildInstance(request);
            return doHandler(request, instance, meta);
        } catch (NacosException e) {
            McpServerEndpointResponse response = new McpServerEndpointResponse();
            response.setErrorInfo(e.getErrCode(), e.getErrMsg());
            return response;
        }
    }
    
    private void checkParameters(McpServerEndpointRequest request) throws NacosApiException {
        if (StringUtils.isBlank(request.getMcpName())) {
            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,
                "parameters `mcpName` can't be empty or null");
        }
    }
    
    private McpServerEndpointResponse doHandler(McpServerEndpointRequest request, Instance instance,
        RequestMeta meta)
        throws NacosException {
        McpServerIndexData indexData = mcpServerIndex.getMcpServerByName(request.getNamespaceId(),
            request.getMcpName());
        if (null == indexData) {
            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.MCP_SERVER_NOT_FOUND,
                String.format("MCP server `%s` not found in namespaceId: `%s`",
                    request.getMcpName(),
                    request.getNamespaceId()));
        }
        McpServerDetailInfo mcpServer =
            mcpServerOperationService.getMcpServerDetail(request.getNamespaceId(),
                indexData.getId(), null, request.getVersion());

View on GitHub (pinned to 9b989acdf1)

Solutions

Set McpServerEndpointRequest.mcpName to the target MCP server's name before sending.
After the call, inspect McpServerEndpointResponse error info (isSuccess / errCode) rather than relying on an exception.
Validate mcpName client-side before invoking the request to avoid the round-trip.

Example fix

// before
McpServerEndpointRequest req = new McpServerEndpointRequest();
req.setType(AiRemoteConstants.REGISTER_ENDPOINT);
req.setAddress("10.0.0.1"); req.setPort(8080);
// mcpName not set -> response error PARAMETER_MISSING

// after
req.setNamespaceId("public");
req.setMcpName("my-mcp-server");

Defensive patterns

Strategy: validation

Validate before calling

if (StringUtils.isBlank(request.getMcpName())) {
    throw new IllegalArgumentException("McpServerEndpointRequest.mcpName must not be blank");
}

Try / catch

McpServerEndpointResponse resp = handler.handle(request, meta);
if (resp.getErrCode() != 0) {
    // handle PARAMETER_MISSING for blank mcpName without an exception
    handleClientError(resp.getErrCode(), resp.getErrMsg());
}

Prevention

Validate mcpName client-side before sending the gRPC request.
Check McpServerEndpointResponse error info after every call; the handler returns errors inside the response, not as exceptions.
Reuse the AiRemoteConstants for type values rather than raw strings.

When it happens

Trigger: A gRPC client sending McpServerEndpointRequest with mcpName null/empty/whitespace to register or deregister an MCP server endpoint (since 3.0.3). The response will carry errCode INVALID_PARAM and the PARAMETER_MISSING detail.

Common situations: An MCP server SDK client that builds the request from config that did not set the server name; a migration where the field was renamed; a test harness that sends a minimal request.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/dbf5452b9a23af60. Report an issue: GitHub.