microsoft/aspire · error · McpProtocolException

InternalError

InternalError

Error message

No Aspire AppHost is currently running. To use Aspire MCP tools, you must first start an Aspire application by running 'aspire start' in your AppHost project directory. Once the application is running, the MCP tools will be able to connect to the dashboard and execute commands.

What it means

MCP tools run inside the Aspire CLI and operate via a backchannel connection to the running AppHost's dashboard. When no AppHost is running (GetSelectedConnectionAsync returns null), the tool throws McpProtocolException with InternalError and a message instructing the user to run 'aspire start' first.

Solutions

Start the AppHost: run 'aspire start' (or the apphost) in your AppHost project directory, then retry
Verify the AppHost is actually running and its dashboard is up
Reconnect/restart the MCP client so it discovers the new backchannel connection
Ensure you are in the correct AppHost project directory if multiple exist

Example fix

// before (no session)
callTool("execute_resource_command", args);
// after
// 1) aspire start   (in the AppHost project directory)
// 2) retry the tool call
callTool("execute_resource_command", args);

Defensive patterns

Strategy: retry

Validate before calling

// before invoking MCP tools, confirm a session exists
var connected = await helper.TryGetSelectedConnectionAsync(monitor, logger, ct);
if (connected is null) { /* prompt user to run 'aspire start' */ }

Try / catch

try { await tool.CallToolAsync(ctx); }
catch (McpProtocolException ex) when (ex.Message.Contains("No Aspire AppHost"))
{ // start the AppHost, wait for dashboard, then retry with backoff }

Prevention

Start the AppHost before launching/using MCP tooling
Health-check the dashboard/backchannel connection before tool calls
Retry with backoff after starting the AppHost; connections appear asynchronously
Scope MCP client config to workspaces that actually have a running AppHost

When it happens

Trigger: Calling execute_resource_command (or any MCP tool using AppHostConnectionHelper) while no Aspire AppHost application is running or connected to the dashboard/backchannel.

Common situations: MCP client configured globally without an active aspire session; AppHost stopped or crashed after client connected; running MCP tools outside the AppHost project directory; multi-AppHost setups where the wrong/none connection is selected.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/0bbe9b2e818fc9db. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Cli/Mcp/Tools/ExecuteResourceCommandTool.cs:90

            throw new McpProtocolException("Arguments 'resourceName' and 'commandName' cannot be empty.", McpErrorCode.InvalidParams);
        }

        JsonNode? commandArguments = null;
        if (toolArguments.TryGetValue("arguments", out var commandArgumentsElement))
        {
            if (commandArgumentsElement.ValueKind != JsonValueKind.Object)
            {
                throw new McpProtocolException("Argument 'arguments' must be a JSON object.", McpErrorCode.InvalidParams);
            }

            commandArguments = CreateCommandArguments(commandArgumentsElement);
        }

        var connection = await AppHostConnectionHelper.GetSelectedConnectionAsync(auxiliaryBackchannelMonitor, logger, cancellationToken).ConfigureAwait(false);
        if (connection is null)
        {
            logger.LogWarning("No Aspire AppHost is currently running");
            throw new McpProtocolException(McpErrorMessages.NoAppHostRunning, McpErrorCode.InternalError);
        }

        // Check if the resource is excluded from MCP before executing commands.
        var excludedResult = await McpToolHelpers.CheckResourceExcludedAsync(connection, resourceName, cancellationToken).ConfigureAwait(false);
        if (excludedResult is not null)
        {
            return excludedResult;
        }

        try
        {
            logger.LogDebug("Executing command '{CommandName}' on resource '{ResourceName}' via backchannel", commandName, resourceName);

            var response = await connection.ExecuteResourceCommandAsync(
                resourceName,
                commandName,
                new ExecuteResourceCommandOptions
                {

View on GitHub (pinned to 25830f84bd)