abpframework/abp · error · CliUsageException

Could not connect to ABP.IO MCP Server. The MCP server requi

Error message

Could not connect to ABP.IO MCP Server. The MCP server requires a connection to fetch tool definitions. Please check your internet connection and try again.

What it means

Thrown by McpCommand when the health check against the ABP.IO MCP Server fails. Before starting the MCP server, the command calls _mcpHttpClient.CheckServerHealthAsync(); if it returns false, the command cannot fetch tool definitions and aborts with CliUsageException. This is a network/connectivity prerequisite check.

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/McpCommand.cs:74

        await ValidateLicenseAsync();

        var option = commandLineArgs.Target;

        if (!string.IsNullOrEmpty(option) && option.Equals("get-config", StringComparison.OrdinalIgnoreCase))
        {
            await PrintConfigurationAsync();
            return;
        }

        await using var _ = _telemetryService.TrackActivityAsync(ActivityNameConsts.AbpCliCommandsMcp);

        // Check server health before starting - fail if not reachable
        _mcpLogger.Info(LogSource, "Checking ABP.IO MCP Server connection...");
        var isHealthy = await _mcpHttpClient.CheckServerHealthAsync();
        
        if (!isHealthy)
        {
            throw new CliUsageException(
                "Could not connect to ABP.IO MCP Server. " +
                "The MCP server requires a connection to fetch tool definitions. " +
                "Please check your internet connection and try again.");
        }

        _mcpLogger.Info(LogSource, "Starting ABP MCP Server...");
        
        var cts = new CancellationTokenSource();
        
        ConsoleCancelEventHandler cancelHandler = (sender, e) =>
        {
            e.Cancel = true;
            _mcpLogger.Info(LogSource, "Shutting down ABP MCP Server...");
            
            try
            {
                cts.Cancel();
            }

View on GitHub (pinned to 7ed43b1931)

Solutions

Verify internet connectivity and that abp.io is reachable: `curl -I https://abp.io`
Configure proxy settings if behind a corporate proxy (HTTP_PROXY/HTTPS_PROXY environment variables)
Check for any firewall rules blocking outbound HTTPS traffic to abp.io
Retry after confirming network stability, as this may be transient server-side downtime
If in an air-gapped environment, the MCP server feature is not available without connectivity

Example fix

N/A

Defensive patterns

Strategy: retry

Validate before calling

// Pre-check connectivity to abp.io before running the MCP command
using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(10) };
try
{
    var response = await client.GetAsync("https://abp.io/api/mcp/health");
    if (!response.IsSuccessStatusCode)
        Console.Error.WriteLine("Warning: ABP.IO MCP server health check failed.");
}
catch
{
    Console.Error.WriteLine("Warning: Cannot reach abp.io. Check network/proxy settings.");
}

Try / catch

for (int attempt = 0; attempt < 3; attempt++)
{
    try
    {
        await mcpCommand.ExecuteAsync(commandLineArgs);
        break;
    }
    catch (CliUsageException ex) when (ex.Message.Contains("Could not connect to ABP.IO MCP Server") && attempt < 2)
    {
        logger.LogWarning("MCP server unreachable, retrying in {0}s...", (attempt + 1) * 5);
        await Task.Delay((attempt + 1) * 5000);
    }
}

Prevention

Configure HTTP_PROXY/HTTPS_PROXY environment variables in corporate networks
Verify outbound HTTPS connectivity to abp.io before running in CI
Understand the MCP feature requires live internet — it is not available air-gapped

When it happens

Trigger: CheckServerHealthAsync() returns false due to: no internet connection, ABP.IO server unreachable, proxy/firewall blocking the request, DNS resolution failure, or the server health endpoint returning a non-success status.

Common situations: Corporate network with strict firewall/proxy rules blocking outbound HTTPS to abp.io, intermittent connectivity during `abp mcp` startup, DNS issues, or ABP.IO server downtime. Also in air-gapped environments where no external connectivity is available.

Related errors

AI-assisted analysis of abpframework/abp@7ed43b1931 (2026-08-13). Data as JSON: /api/errors/89778d2a1ed99a5f. Report an issue: GitHub.