{"record":{"id":"0b5b0aa05e6c0739","repo":"alibaba/nacos","slug":"mcp-server-not-found","errorCode":"MCP_SERVER_NOT_FOUND","errorMessage":"MCP server `%s` not found in namespaceId: `%s`","messagePattern":"MCP server `(.+?)` not found in namespaceId: `(.+?)`","errorType":"exception","errorClass":"NacosApiException","httpStatus":404,"severity":"warning","filePath":"ai/src/main/java/com/alibaba/nacos/ai/remote/handler/McpServerEndpointRequestHandler.java","lineNumber":115,"sourceCode":"            response.setErrorInfo(e.getErrCode(), e.getErrMsg());\n            return response;\n        }\n    }\n    \n    private void checkParameters(McpServerEndpointRequest request) throws NacosApiException {\n        if (StringUtils.isBlank(request.getMcpName())) {\n            throw new NacosApiException(NacosException.INVALID_PARAM, ErrorCode.PARAMETER_MISSING,\n                \"parameters `mcpName` can't be empty or null\");\n        }\n    }\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: {}\",","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/ai/src/main/java/com/alibaba/nacos/ai/remote/handler/McpServerEndpointRequestHandler.java#L97-L133","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Create/release the MCP server first (ReleaseMcpServerRequest) so it exists in the target namespace.","Verify the mcpName and namespaceId match an existing server via the MCP server query API.","Ensure the client sends the correct namespaceId (it defaults via McpRequestUtil.fillNamespaceId, but an explicit wrong value overrides it)."],"exampleFix":"// before\nreq.setMcpName(\"my-mcp\"); // server published under \"my-mcp-server\"\n\n// after\nreq.setMcpName(\"my-mcp-server\");\nreq.setNamespaceId(\"public\");","handlingStrategy":"validation","validationCode":"// Confirm the server exists before registering endpoints\nMcpServerDetailInfo detail = mcpServerOperationService\n    .getMcpServerDetail(namespaceId, null, mcpName, null);\nif (detail == null) {\n    throw new IllegalStateException(\"MCP server '\" + mcpName + \"' not found; release it first.\");\n}","typeGuard":null,"tryCatchPattern":"McpServerEndpointResponse resp = handler.handle(request, meta);\nif (ErrorCode.MCP_SERVER_NOT_FOUND.getCode() == resp.getDetailErrCode()) {\n    // server missing: create/release it first, then retry registration\n    releaseMcpServer(request.getNamespaceId(), request.getMcpName());\n}","preventionTips":["Release the MCP server before any endpoint register/deregister.","Verify namespaceId and mcpName against the server query API.","Treat MCP_SERVER_NOT_FOUND responses as recoverable by releasing the server, not by blind retry."],"tags":["ai","mcp-server","grpc","not-found","endpoint"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}