{"record":{"id":"93b0cb62ec15869c","repo":"alibaba/nacos","slug":"mcp-server-ref-endpoint-service-not-found","errorCode":"MCP_SERVER_REF_ENDPOINT_SERVICE_NOT_FOUND","errorMessage":"The Mcp Server Ref endpoint service not found.","messagePattern":"The Mcp Server Ref endpoint service not found\\.","errorType":"exception","errorClass":"NacosApiException","httpStatus":404,"severity":"error","filePath":"ai/src/main/java/com/alibaba/nacos/ai/remote/handler/McpServerEndpointRequestHandler.java","lineNumber":125,"sourceCode":"    }\n    \n    private McpServerEndpointResponse doHandler(McpServerEndpointRequest request, Instance instance,\n        RequestMeta meta)\n        throws NacosException {\n        McpServerIndexData indexData = mcpServerIndex.getMcpServerByName(request.getNamespaceId(),\n            request.getMcpName());\n        if (null == indexData) {\n            throw new NacosApiException(NacosException.NOT_FOUND, ErrorCode.MCP_SERVER_NOT_FOUND,\n                String.format(\"MCP server `%s` not found in namespaceId: `%s`\",\n                    request.getMcpName(),\n                    request.getNamespaceId()));\n        }\n        McpServerDetailInfo mcpServer =\n            mcpServerOperationService.getMcpServerDetail(request.getNamespaceId(),\n                indexData.getId(), null, request.getVersion());\n        McpServiceRef serviceRef = buildServiceRef(mcpServer);\n        if (null == serviceRef) {\n            throw new NacosApiException(NacosException.NOT_FOUND,\n                ErrorCode.MCP_SERVER_REF_ENDPOINT_SERVICE_NOT_FOUND,\n                \"The Mcp Server Ref endpoint service not found.\");\n        }\n        Service service = Service.newService(request.getNamespaceId(), serviceRef.getGroupName(),\n            serviceRef.getServiceName(), true);\n        switch (request.getType()) {\n            case AiRemoteConstants.REGISTER_ENDPOINT:\n                LOGGER.info(\"[{}] register endpoint {}:{} version {} for mcp server: {}\",\n                    meta.getConnectionId(),\n                    request.getAddress(), request.getPort(), request.getVersion(),\n                    request.getMcpName());\n                doRegister(service, instance, meta);\n                break;\n            case AiRemoteConstants.DE_REGISTER_ENDPOINT:\n                LOGGER.info(\"[{}] de-register endpoint {}:{} version {} for mcp server: {}\",\n                    meta.getConnectionId(),\n                    request.getAddress(), request.getPort(), request.getVersion(),\n                    request.getMcpName());","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/remote/handler/McpServerEndpointRequestHandler.java#L107-L143","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-publish the MCP server (ReleaseMcpServerRequest) with a valid endpointSpecification / serviceRef so the naming service target is set.","For HTTP servers, ensure at least one FrontEndpointConfig uses endpointType MCP_ENDPOINT_TYPE_REF pointing to a naming service.","Inspect the MCP server detail (getMcpServerDetail) to confirm remoteServerConfig.serviceRef or the front endpoint list before registering endpoints."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"McpServerDetailInfo info = mcpServerOperationService\n    .getMcpServerDetail(namespaceId, id, mcpName, version);\nMcpServiceRef ref = (isHttp(info)) ? findRefFrontEndpoint(info) : info.getRemoteServerConfig().getServiceRef();\nif (ref == null) {\n    throw new IllegalStateException(\n        \"MCP server has no endpoint service ref; re-publish with a valid endpointSpecification.\");\n}","typeGuard":null,"tryCatchPattern":"McpServerEndpointResponse resp = handler.handle(request, meta);\nif (ErrorCode.MCP_SERVER_REF_ENDPOINT_SERVICE_NOT_FOUND.getCode() == resp.getDetailErrCode()) {\n    // re-publish server with a proper serviceRef / REF front endpoint, then retry\n    republishWithEndpointSpec(request.getNamespaceId(), request.getMcpName());\n}","preventionTips":["Always publish MCP servers with an endpointSpecification (or rely on auto-build for non-stdio protocols).","For HTTP servers, include at least one FrontEndpointConfig of type MCP_ENDPOINT_TYPE_REF.","Inspect getMcpServerDetail.remoteServerConfig before registering endpoints to catch a null serviceRef early."],"tags":["ai","mcp-server","grpc","configuration","endpoint","not-found"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}