abpframework/abp · error · CliUsageException

Failed to fetch tool definitions: {errorMessage}

Error message

Failed to fetch tool definitions: {errorMessage}

What it means

Thrown by McpHttpClientService.GetToolDefinitionsAsync when the HTTP GET request to {baseUrl}/tools returns a non-success HTTP status code. The error message is sanitized via GetSanitizedHttpErrorMessage to avoid exposing raw server responses. Status code mappings include: 401 -> authentication failure, 403 -> access denied, 404 -> tool not found, 429 -> rate limit, 503 -> service unavailable.

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/Services/McpHttpClientService.cs:149

    public async Task<List<McpToolDefinition>> GetToolDefinitionsAsync()
    {
        _mcpLogger.Debug(LogSource, $"GetToolDefinitionsAsync called. Instance={GetHashCode()}");
        
        var baseUrl = await GetMcpServerUrlAsync();
        var url = $"{baseUrl}/tools";

        try
        {
            using var httpClient = _httpClientFactory.CreateClient(needsAuthentication: true);
            var response = await httpClient.GetAsync(url);

            if (!response.IsSuccessStatusCode)
            {
                _mcpLogger.Error(LogSource, $"Failed to fetch tool definitions with status: {response.StatusCode}");
                
                // Throw sanitized exception
                var errorMessage = GetSanitizedHttpErrorMessage(response.StatusCode);
                throw new CliUsageException($"Failed to fetch tool definitions: {errorMessage}");
            }

            var responseContent = await response.Content.ReadAsStringAsync();
            
            // The API returns { tools: [...] } format
            var result = JsonSerializer.Deserialize<McpToolsResponse>(responseContent, JsonSerializerOptionsWeb);
            var tools = result?.Tools ?? new List<McpToolDefinition>();
            
            // Cache tool names for validation
            _validToolNames = tools.Select(t => t.Name).ToList();
            _toolDefinitionsLoaded = true;
            
            _mcpLogger.Debug(LogSource, $"Tool definitions loaded successfully. _toolDefinitionsLoaded={_toolDefinitionsLoaded}, Tool count={tools.Count}, Instance={GetHashCode()}");
            
            return tools;
        }
        catch (HttpRequestException ex)
        {

View on GitHub (pinned to 7ed43b1931)

Solutions

1. Run 'abp login' to authenticate with your ABP account
2. Verify your ABP Commercial license is active and covers MCP tool access
3. Wait 30-60 seconds and retry if rate-limited (429 status)
4. Check ABP.IO service status pages for known outages
5. Verify network/proxy/firewall allows outbound HTTPS to the MCP server URL
6. If using a custom MCP server URL, verify it in CliPaths.McpConfig

// Pre-check: verify authentication and server reachability before fetching tools
var isHealthy = await _mcpHttpClient.CheckServerHealthAsync();
if (!isHealthy)
{
    Console.Error.WriteLine("MCP server is not reachable. Check network and authentication.");
    return;
}

// Retry with exponential backoff for transient HTTP failures
async Task<List<McpToolDefinition>> FetchWithRetry(int maxRetries = 3)
{
    for (int i = 0; i < maxRetries; i++)
    {
        try
        {
            return await _mcpHttpClient.GetToolDefinitionsAsync();
        }
        catch (CliUsageException ex) when (ex.Message.Contains("Failed to fetch") && i < maxRetries - 1)
        {
            await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, i)));
        }
    }
    throw new InvalidOperationException("Failed to fetch tool definitions after retries.");
}

When it happens

Trigger: The ABP.IO MCP server's /tools endpoint returns an error HTTP status. This occurs when: the CLI is not authenticated (401), the account lacks MCP feature access (403), the server is rate-limiting (429), or the server is down (503/500). The HTTP client is created with needsAuthentication: true, so it includes auth headers.

Common situations: CLI not logged in (run 'abp login'), expired authentication token, ABP Commercial license expired or insufficient tier for MCP features, ABP.IO server outage or maintenance, corporate proxy blocking access, rate limiting from too many requests.

Related errors

• Could not connect to ABP.IO MCP Server. The MCP server requi
• Please log in with your account!
• Tool definitions have not been loaded yet. This is an intern
• Failed to fetch tool definitions from ABP.IO MCP Server. No
• ERROR: Remote server returns '{response.StatusCode}'

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