alibaba/nacos · error · NacosApiException

MCP_SERVER_REF_ENDPOINT_SERVICE_NOT_FOUND

MCP_SERVER_REF_ENDPOINT_SERVICE_NOT_FOUND

Error message

The Mcp Server Ref endpoint service not found.

What it means

Thrown by McpServerEndpointRequestHandler.doHandler() when buildServiceRef(mcpServer) returns null. For stdio/BACKEND servers this happens when remoteServerConfig.getServiceRef() is null; for HTTP (frontend) servers it happens when no FrontEndpointConfig with endpointType REF exists in the front endpoint list. Mapped to MCP_SERVER_REF_ENDPOINT_SERVICE_NOT_FOUND with a NOT_FOUND top-level code, indicating the server exists but has no backing naming service to register into.

Source

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

    }
    
    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: {}",
                    meta.getConnectionId(),
                    request.getAddress(), request.getPort(), request.getVersion(),
                    request.getMcpName());
                doRegister(service, instance, meta);
                break;
            case AiRemoteConstants.DE_REGISTER_ENDPOINT:
                LOGGER.info("[{}] de-register endpoint {}:{} version {} for mcp server: {}",
                    meta.getConnectionId(),
                    request.getAddress(), request.getPort(), request.getVersion(),
                    request.getMcpName());

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Re-publish the MCP server (ReleaseMcpServerRequest) with a valid endpointSpecification / serviceRef so the naming service target is set.
  2. For HTTP servers, ensure at least one FrontEndpointConfig uses endpointType MCP_ENDPOINT_TYPE_REF pointing to a naming service.
  3. Inspect the MCP server detail (getMcpServerDetail) to confirm remoteServerConfig.serviceRef or the front endpoint list before registering endpoints.
Defensive patterns

Strategy: validation

Validate before calling

McpServerDetailInfo info = mcpServerOperationService
    .getMcpServerDetail(namespaceId, id, mcpName, version);
McpServiceRef ref = (isHttp(info)) ? findRefFrontEndpoint(info) : info.getRemoteServerConfig().getServiceRef();
if (ref == null) {
    throw new IllegalStateException(
        "MCP server has no endpoint service ref; re-publish with a valid endpointSpecification.");
}

Try / catch

McpServerEndpointResponse resp = handler.handle(request, meta);
if (ErrorCode.MCP_SERVER_REF_ENDPOINT_SERVICE_NOT_FOUND.getCode() == resp.getDetailErrCode()) {
    // re-publish server with a proper serviceRef / REF front endpoint, then retry
    republishWithEndpointSpec(request.getNamespaceId(), request.getMcpName());
}

Prevention

When it happens

Trigger: Endpoint register/deregister against an MCP server whose remoteServerConfig is missing a serviceRef (non-HTTP) or whose HTTP front endpoint list has no REF-type entry. The server was found but is incompletely or incorrectly configured.

Common situations: An MCP server created via a path that did not set the endpoint service reference; an HTTP-protocol server whose frontEndpointConfigList only contains DIRECT endpoints; a stdio server that was meant to use auto-built endpoint spec but was published with a null serviceRef; data corruption in the server detail record.

Related errors

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