{"record":{"id":"3ed15368f1a159ff","repo":"microsoft/aspire","slug":"failed-to-create-mcp-client","errorCode":null,"errorMessage":"Failed to create MCP client.","messagePattern":"Failed to create MCP client\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/Backchannel/AuxiliaryBackchannelRpcTarget.cs","lineNumber":1812,"sourceCode":"\n        if (!resource.TryGetLastAnnotation<McpServerEndpointAnnotation>(out var annotation))\n        {\n            throw new InvalidOperationException($\"Resource '{resourceName}' does not have an MCP endpoint annotation.\");\n        }\n\n        var endpointUri = await annotation.EndpointUrlResolver(resource, cancellationToken).ConfigureAwait(false);\n        if (endpointUri is null)\n        {\n            throw new InvalidOperationException($\"MCP endpoint for resource '{resourceName}' is not available.\");\n        }\n\n        var transport = CreateHttpClientTransport(endpointUri);\n\n        McpClient? mcpClient = null;\n        try\n        {\n            mcpClient = await McpClient.CreateAsync(transport, cancellationToken: cancellationToken).ConfigureAwait(false)\n                ?? throw new InvalidOperationException(\"Failed to create MCP client.\");\n\n            if (logger.IsEnabled(LogLevel.Debug))\n            {\n                logger.LogDebug(\"Invoking tool {Name} with arguments {Arguments}\", toolName, JsonSerializer.Serialize(arguments));\n            }\n\n            var result = await mcpClient.CallToolAsync(toolName, arguments, cancellationToken: cancellationToken).ConfigureAwait(false);\n\n            if (logger.IsEnabled(LogLevel.Debug))\n            {\n                logger.LogDebug(\"Result: {Result}\", JsonSerializer.Serialize(result));\n            }\n\n            return result;\n        }\n        catch (Exception ex)\n        {\n            logger.LogError(ex, \"Error invoking tool {ToolName} on resource {ResourceName}\", toolName, resourceName);","sourceCodeStart":1794,"sourceCodeEnd":1830,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/Backchannel/AuxiliaryBackchannelRpcTarget.cs#L1794-L1830","documentation":"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.","triggerScenarios":"Calling the backchannel MCP tool invocation method when McpClient.CreateAsync(transport) returns null instead of a client instance.","commonSituations":"MCP SDK version changes or edge cases where the client factory yields null; transport misconfiguration that the SDK does not surface as an exception.","solutions":["Check that the MCP SDK transport and endpoint URI are valid and the server responds to MCP initialization.","Verify package versions of ModelContextProtocol match what Aspire expects.","Wrap the call and surface the endpoint health; if the server is reachable the client should be created normally.","If it reproduces consistently, capture logs at Debug level around client creation for the underlying cause."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Probe the endpoint before creating the client\nusing var http = new HttpClient { BaseAddress = endpointUri };\nvar ok = (await http.SendAsync(new HttpRequestMessage(HttpMethod.Get, \"/\"))).IsSuccessStatusCode;","typeGuard":null,"tryCatchPattern":"try\n{\n    mcpClient = await McpClient.CreateAsync(transport, cancellationToken: ct);\n}\ncatch (Exception ex)\n{\n    logger.LogError(ex, \"MCP client creation failed for {Endpoint}\", endpointUri);\n    throw new InvalidOperationException($\"Failed to create MCP client for {endpointUri}.\", ex);\n}","preventionTips":["Keep ModelContextProtocol SDK packages aligned with the Aspire version.","Confirm the MCP server endpoint responds before invoking tools.","Enable debug logging around client creation to capture root causes."],"tags":["mcp","client","backchannel","aspire"],"backgroundTag":"internal-invariant-violation","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T09:17:21.228Z"}