microsoft/aspire · error · InvalidOperationException

Failed to create MCP client.

Error message

Failed to create MCP client.

What it means

Thrown when McpClient.CreateAsync returns null while trying to connect to a resource's MCP server over an HTTP transport. The library treats a null client as a creation failure since a tool cannot be invoked without a client instance.

Solutions

1. Check that the MCP SDK transport and endpoint URI are valid and the server responds to MCP initialization.
2. Verify package versions of ModelContextProtocol match what Aspire expects.
3. Wrap the call and surface the endpoint health; if the server is reachable the client should be created normally.
4. If it reproduces consistently, capture logs at Debug level around client creation for the underlying cause.

// Probe the endpoint before creating the client
using var http = new HttpClient { BaseAddress = endpointUri };
var ok = (await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, "/"))).IsSuccessStatusCode;

try
{
    mcpClient = await McpClient.CreateAsync(transport, cancellationToken: ct);
}
catch (Exception ex)
{
    logger.LogError(ex, "MCP client creation failed for {Endpoint}", endpointUri);
    throw new InvalidOperationException($"Failed to create MCP client for {endpointUri}.", ex);
}

When it happens

Trigger: Calling the backchannel MCP tool invocation method when McpClient.CreateAsync(transport) returns null instead of a client instance.

Common situations: MCP SDK version changes or edge cases where the client factory yields null; transport misconfiguration that the SDK does not surface as an exception.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• MCP endpoint for resource
• A global MCP approval policy cannot be combined with custom…
• An MCP approval filter must specify at least one tool name…
• An MCP approval policy must specify a global mode or at…
• Could not create MCP server for resource

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

Appendix: source

Thrown at src/Aspire.Hosting/Backchannel/AuxiliaryBackchannelRpcTarget.cs:1812

        if (!resource.TryGetLastAnnotation<McpServerEndpointAnnotation>(out var annotation))
        {
            throw new InvalidOperationException($"Resource '{resourceName}' does not have an MCP endpoint annotation.");
        }

        var endpointUri = await annotation.EndpointUrlResolver(resource, cancellationToken).ConfigureAwait(false);
        if (endpointUri is null)
        {
            throw new InvalidOperationException($"MCP endpoint for resource '{resourceName}' is not available.");
        }

        var transport = CreateHttpClientTransport(endpointUri);

        McpClient? mcpClient = null;
        try
        {
            mcpClient = await McpClient.CreateAsync(transport, cancellationToken: cancellationToken).ConfigureAwait(false)
                ?? throw new InvalidOperationException("Failed to create MCP client.");

            if (logger.IsEnabled(LogLevel.Debug))
            {
                logger.LogDebug("Invoking tool {Name} with arguments {Arguments}", toolName, JsonSerializer.Serialize(arguments));
            }

            var result = await mcpClient.CallToolAsync(toolName, arguments, cancellationToken: cancellationToken).ConfigureAwait(false);

            if (logger.IsEnabled(LogLevel.Debug))
            {
                logger.LogDebug("Result: {Result}", JsonSerializer.Serialize(result));
            }

            return result;
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Error invoking tool {ToolName} on resource {ResourceName}", toolName, resourceName);

View on GitHub (pinned to 25830f84bd)