alibaba/nacos · error · NacosApiException

API_FUNCTION_DISABLED

API_FUNCTION_DISABLED

Error message

Nacos AI MCP module and API required both `naming` and `config` module.

What it means

This error is thrown by McpNoopHandler.listMcpServers when listing MCP (Model Context Protocol) servers. The noop handler is a @ConditionalOnMissingBean fallback that activates when the real McpHandler (McpInnerHandler or McpRemoteHandler) was not loaded. The real handlers require @EnabledAiHandler, which needs both naming and config modules to be active. HTTP status is 501 (SERVER_NOT_IMPLEMENTED) with ErrorCode.API_FUNCTION_DISABLED (40001).

Source

Thrown at console/src/main/java/com/alibaba/nacos/console/handler/impl/noop/ai/McpNoopHandler.java:51

/**
 * Noop implementation of Mcp handler.
 * Used when `naming` or `config` module are not enabled.
 *
 * @author xiweng.yy
 */
@Service
@ConditionalOnMissingBean(value = McpHandler.class, ignored = McpNoopHandler.class)
public class McpNoopHandler implements McpHandler {
    
    private static final String MCP_NOT_ENABLED_MESSAGE =
        "Nacos AI MCP module and API required both `naming` and `config` module.";
    
    @Override
    public Page<McpServerBasicInfo> listMcpServers(String namespaceId, String mcpName,
        String search, int pageNo,
        int pageSize) throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            MCP_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public McpServerDetailInfo getMcpServer(String namespaceId, String mcpName, String mcpId,
        String version)
        throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,
            ErrorCode.API_FUNCTION_DISABLED,
            MCP_NOT_ENABLED_MESSAGE);
    }
    
    @Override
    public String createMcpServer(String namespaceId, McpServerBasicInfo serverSpecification,
        McpToolSpecification toolSpecification, McpEndpointSpec endpointSpecification)
        throws NacosException {
        throw new NacosApiException(NacosException.SERVER_NOT_IMPLEMENTED,

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Unset functionMode (enable all modules) or set it to 'ai' / 'microservice'.
  2. Verify nacos.extension.ai.enabled is not explicitly false in application.properties or JVM args.
  3. Restart the Nacos server so Spring re-evaluates @ConditionalOnMissingBean and loads the real McpHandler.

Example fix

# before (config-only deployment)
java -Dnacos.functionMode=config -jar nacos-server.jar

# after (enable AI/MCP support)
java -Dnacos.functionMode=ai -jar nacos-server.jar
Defensive patterns

Strategy: try-catch

Validate before calling

// Probe MCP availability before calling listMcpServers
public boolean isMcpAvailable(NacosRestTemplate restTemplate, String baseUrl) {
    try {
        restTemplate.get(
            baseUrl + "/v3/console/ai/mcp/list?pageNo=1&pageSize=1",
            String.class);
        return true;
    } catch (NacosApiException e) {
        return e.getErrCode() != NacosException.SERVER_NOT_IMPLEMENTED;
    }
}

Try / catch

try {
    Page<McpServerBasicInfo> servers = mcpHandler.listMcpServers(
        namespaceId, mcpName, search, pageNo, pageSize);
} catch (NacosApiException e) {
    if (e.getErrCode() == NacosException.SERVER_NOT_IMPLEMENTED
        && ErrorCode.API_FUNCTION_DISABLED.getCode() == e.getDetailErrCode()) {
        // MCP module not enabled — return empty result or notify user
        log.warn("MCP list failed: AI module not enabled on server.");
        return new Page<>();
    }
    throw e;
}

Prevention

When it happens

Trigger: A client calls GET /v3/console/ai/mcp/list or GET /v3/admin/ai/mcp/server/list on a Nacos server whose functionMode is 'config' or 'naming' (single-module), or where nacos.extension.ai.enabled=false. ConditionAiEnabled.matches() returns false.

Common situations: Developers integrating MCP tool servers into their LLM workflows who point their MCP registry client at a Nacos node deployed for traditional config/service-discovery. Also occurs after upgrading Nacos to a version with MCP support without updating the functionMode that was set on the old version.

Related errors

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