alibaba/nacos · warning · NacosApiException

MCP_SERVER_NOT_FOUND

MCP_SERVER_NOT_FOUND

Error message

MCP server `%s` not found in namespaceId: `%s`

What it means

Thrown by McpServerEndpointRequestHandler.doHandler() when McpServerIndex.getMcpServerByName(namespaceId, mcpName) returns null, meaning no MCP server with that name exists in the given namespace. Mapped to MCP_SERVER_NOT_FOUND with a NOT_FOUND top-level code. Like other handler errors it is caught and placed into the response error info rather than thrown to the gRPC transport.

Source

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

            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());
        McpServiceRef serviceRef = buildServiceRef(mcpServer);
        if (null == serviceRef) {
            throw new NacosApiException(NacosException.NOT_FOUND,
                ErrorCode.MCP_SERVER_REF_ENDPOINT_SERVICE_NOT_FOUND,
                "The Mcp Server Ref endpoint service not found.");
        }
        Service service = Service.newService(request.getNamespaceId(), serviceRef.getGroupName(),
            serviceRef.getServiceName(), true);
        switch (request.getType()) {
            case AiRemoteConstants.REGISTER_ENDPOINT:
                LOGGER.info("[{}] register endpoint {}:{} version {} for mcp server: {}",

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Create/release the MCP server first (ReleaseMcpServerRequest) so it exists in the target namespace.
2. Verify the mcpName and namespaceId match an existing server via the MCP server query API.
3. Ensure the client sends the correct namespaceId (it defaults via McpRequestUtil.fillNamespaceId, but an explicit wrong value overrides it).

Example fix

// before
req.setMcpName("my-mcp"); // server published under "my-mcp-server"

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

// Confirm the server exists before registering endpoints
McpServerDetailInfo detail = mcpServerOperationService
    .getMcpServerDetail(namespaceId, null, mcpName, null);
if (detail == null) {
    throw new IllegalStateException("MCP server '" + mcpName + "' not found; release it first.");
}

McpServerEndpointResponse resp = handler.handle(request, meta);
if (ErrorCode.MCP_SERVER_NOT_FOUND.getCode() == resp.getDetailErrCode()) {
    // server missing: create/release it first, then retry registration
    releaseMcpServer(request.getNamespaceId(), request.getMcpName());
}

When it happens

Trigger: Registering or deregistering an endpoint for an MCP server name that was never created, was deleted, or lives in a different namespaceId. Fires after checkParameters passes and before the endpoint service ref is resolved.

Common situations: Calling register endpoint before release MCP server; wrong namespaceId (e.g. default 'public' vs a custom namespace); a typo in the mcpName; the server was cleaned up between discovery and registration.

Related errors

• MCP_SERVER_REF_ENDPOINT_SERVICE_NOT_FOUND
• PARAMETER_MISSING
• PARAMETER_VALIDATE_ERROR
• PARAMETER_MISSING
• MCP_SERVER_VERSION_EXIST

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