abpframework/abp · critical · CliUsageException

Failed to fetch tool definitions from ABP.IO MCP Server. No

Error message

Failed to fetch tool definitions from ABP.IO MCP Server. No tools available. The MCP server cannot start without tool definitions.

What it means

Thrown by McpToolsCacheService.GetToolDefinitionsAsync when the server fetch (via _mcpHttpClient.GetToolDefinitionsAsync) returned a successful HTTP response but the deserialized tool list is null or empty (Count == 0). The MCP server cannot function without at least one tool definition, so this is treated as a fatal startup error. This occurs only when the cache is invalid/missing and the server fallback also yields no tools.

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/Services/McpToolsCacheService.cs:59

        {
            var cachedTools = await LoadFromCacheAsync();
            if (cachedTools != null)
            {
                _mcpLogger.Debug(LogSource, "Using cached tool definitions");
                // Initialize the HTTP client's tool names list from cache
                _mcpHttpClient.InitializeToolNames(cachedTools);
                return cachedTools;
            }
        }

        // Cache is invalid or missing, fetch from server
        _mcpLogger.Info(LogSource, "Fetching tool definitions from server...");
        var tools = await _mcpHttpClient.GetToolDefinitionsAsync();
        
        // Validate that we got tools
        if (tools == null || tools.Count == 0)
        {
            throw new CliUsageException(
                "Failed to fetch tool definitions from ABP.IO MCP Server. " +
                "No tools available. The MCP server cannot start without tool definitions.");
        }
        
        // Save tools to cache
        await SaveToCacheAsync(tools);
        await _memoryService.SetAsync(CliConsts.MemoryKeys.McpToolsLastFetchDate, DateTime.Now.ToString(CultureInfo.InvariantCulture));
        
        _mcpLogger.Info(LogSource, $"Successfully fetched and cached {tools.Count} tool definitions");
        return tools;
    }

    private async Task<bool> IsCacheValidAsync()
    {
        try
        {
            // Check if cache file exists
            if (!File.Exists(CliPaths.McpToolsCache))

View on GitHub (pinned to 7ed43b1931)

Solutions

1. Update the ABP CLI to the latest version: 'dotnet tool update -g Volo.Abp.Cli'
2. Verify your ABP account has MCP tool access enabled in the ABP.IO portal
3. Clear the cache and retry: delete CliPaths.McpToolsCache file
4. Contact ABP support if the issue persists across CLI versions

// Pre-validate that the server returns tools before depending on them
var tools = await _mcpHttpClient.GetToolDefinitionsAsync();
if (tools == null || tools.Count == 0)
{
    Console.Error.WriteLine("Server returned no tools. Verify your ABP account and CLI version.");
    return;
}

try
{
    var tools = await _mcpToolsCacheService.GetToolDefinitionsAsync();
}
catch (CliUsageException ex) when (ex.Message.Contains("No tools available"))
{
    // Fall back to stale cache if available, or report error
    Console.Error.WriteLine("No tools available from server. Check ABP account permissions and CLI version.");
}

When it happens

Trigger: The /tools endpoint responds with HTTP 200 but the body is {"tools":[]} or a response that deserializes to an empty list. The cache check (IsCacheValidAsync) already failed, so the code falls through to the server fetch path.

Common situations: ABP.IO MCP server is in a degraded state returning empty tool lists, API version mismatch between CLI and server (response format changed), account has no tools assigned/enabled, server-side configuration error removing all tools.

Related errors

• Tool definitions have not been loaded yet. This is an intern
• Failed to fetch tool definitions: {errorMessage}
• The following background job(s) are configured for more than
• The distributed lock name '{configuration.LockName}' is used
• No background job is registered for the args type '{argsType

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