microsoft/aspire · error · InvalidOperationException

Toolbox MCP request failed

Error message

Toolbox MCP request failed: {error.GetRawText()}

What it means

Thrown by SendRequestAsync when the JSON-RPC response correlated to the expected ID contains an 'error' member. This surfaces the remote Toolbox/MCP server-side error (method not found, invalid params, auth failure, etc.) verbatim from error.GetRawText() as an InvalidOperationException locally.

Solutions

  1. Read the raw error text in the exception message — it names the exact server-side cause.
  2. Fix authentication: ensure the access token has the correct Foundry/Toolbox scopes.
  3. Check that the MCP method/params sent match the server's protocol version; update the Aspire.Hosting.Foundry package if the server is newer.
  4. Inspect Toolbox server logs around the failure time for the underlying exception.

Example fix

// before
// token from stale MicrosoftEntra credentials
token = await oldCredential.GetTokenAsync(scope);
// after
token = (await defaultAzureCredential.GetTokenAsync(new TokenRequestContext(["https://ai.azure.com/.default"]), ct)).Token;
Defensive patterns

Strategy: try-catch

Validate before calling

// Before probing, verify the token is valid for the Foundry scope:
// var tok = await credential.GetTokenAsync(new TokenRequestContext(["https://ai.azure.com/.default"]), ct);

Try / catch

try
{
    await probe.WaitForToolsAsync(accessToken, ct);
}
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Toolbox MCP request failed:"))
{
    // ex.Message carries the raw JSON-RPC error payload; log it verbatim for diagnosis.
    logger.LogError(ex, "Toolbox rejected an MCP request.");
    throw;
}

Prevention

When it happens

Trigger: Any initialize or tools/list request that the Toolbox MCP server answers with a JSON-RPC error object — invalid session ID, unsupported method, malformed request payload, insufficient permissions, or server-side failure.

Common situations: Token lacks the required Foundry scope (401/403 mapped to a JSON-RPC error); the probe sends a method the deployed server version doesn't implement; session was invalidated server-side between requests; request payload doesn't match the server's expected schema.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxReadinessProbe.cs:222

            using var candidate = JsonDocument.Parse(responseMessage);
            if (candidate.RootElement.TryGetProperty("id", out var responseId) &&
                responseId.ValueKind == JsonValueKind.Number &&
                responseId.GetInt32() == expectedId)
            {
                matchingResponse = candidate.RootElement.Clone();
                break;
            }
        }

        if (matchingResponse is null)
        {
            throw new InvalidOperationException(
                $"The Toolbox MCP response did not contain JSON-RPC response ID {expectedId}.");
        }

        if (matchingResponse.Value.TryGetProperty("error", out var error))
        {
            throw new InvalidOperationException($"Toolbox MCP request failed: {error.GetRawText()}");
        }

        var result = matchingResponse.Value.TryGetProperty("result", out var resultElement)
            ? resultElement.Clone()
            : default;
        return new(result, responseSessionId);
    }

    private sealed record McpResponse(
        JsonElement Result,
        string? SessionId,
        bool IsRetryableFailure = false);
}

View on GitHub (pinned to 25830f84bd)