microsoft/aspire · error · ArgumentException

The MCP endpoint must be a Foundry-reachable absolute HTTPS…

Error message

The MCP endpoint must be a Foundry-reachable absolute HTTPS URI.

What it means

Thrown by the string-based WithMcpTool overload when the endpoint fails Uri.TryCreate with UriKind.Absolute or fails FoundryToolboxMcpToolDefinition.IsFoundryReachableHttpsEndpoint. The Toolbox requires an absolute https:// URI that Foundry can reach, so relative URLs, http:// URLs, or malformed strings are rejected at the argument-validation stage.

Solutions

1. Prefix the endpoint with https:// so it parses as an absolute URI.
2. Ensure the host is reachable over HTTPS by Foundry (public or Azure-network-reachable TLS endpoint).
3. Use Uri.TryCreate in your own code to validate the string before passing it.

Example fix

// before
builder.WithMcpTool("search", "my-mcp.example.com/mcp");
// after
builder.WithMcpTool("search", "https://my-mcp.example.com/mcp");

if (!Uri.TryCreate(endpoint, UriKind.Absolute, out var uri) ||
    uri.Scheme != Uri.UriSchemeHttps)
{
    throw new ArgumentException($"MCP endpoint '{endpoint}' must be an absolute https:// URL.", nameof(endpoint));
}
builder.WithMcpTool(name, uri.AbsoluteUri, options);

static bool IsHttpsAbsolute(string? s) =>
    Uri.TryCreate(s, UriKind.Absolute, out var u) && u.Scheme == Uri.UriSchemeHttps;

try
{
    builder.WithMcpTool(name, endpoint, options);
}
catch (ArgumentException ex) when (ex.Message.Contains("Foundry-reachable absolute HTTPS URI"))
{
    logger.LogError(ex, "Invalid MCP endpoint '{Endpoint}' for tool {Tool}.", endpoint, name);
    throw;
}

When it happens

Trigger: Calling builder.WithMcpTool(name, "localhost:8080/mcp") (no scheme), "http://host/mcp" (not https), "" or whitespace (caught earlier by ThrowIfNullOrEmpty), or a syntactically broken URL string.

Common situations: Passing a config value that omits https://; using an http:// local dev endpoint; accidentally passing a path fragment instead of a full URL; hardcoding a URL with a typo or missing scheme.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Endpoint must be a string, endpoint reference, or reference…
• The apiPath must contain only URL-safe path characters…
• The Foundry Local endpoint must be an absolute HTTP or…
• Toolbox ' ' contains duplicate tool names: .
• Toolbox ' ' did not resolve to an absolute HTTPS endpoint.

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs:228

    /// </summary>
    /// <param name="builder">The resource builder for the Toolbox.</param>
    /// <param name="name">The tool name.</param>
    /// <param name="endpoint">The MCP endpoint URI.</param>
    /// <param name="options">Optional MCP server metadata and approval policy.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/> for chaining.</returns>
    /// <ats-returns>The resource builder.</ats-returns>
    [AspireExportIgnore(Reason = "Polyglot app hosts use the union overload instead.")]
    public static IResourceBuilder<FoundryToolboxResource> WithMcpTool(
        this IResourceBuilder<FoundryToolboxResource> builder,
        string name,
        string endpoint,
        FoundryToolboxMcpToolOptions? options = null)
    {
        ArgumentException.ThrowIfNullOrEmpty(endpoint);
        if (!Uri.TryCreate(endpoint, UriKind.Absolute, out var endpointUri) ||
            !FoundryToolboxMcpToolDefinition.IsFoundryReachableHttpsEndpoint(endpointUri))
        {
            throw new ArgumentException(
                "The MCP endpoint must be a Foundry-reachable absolute HTTPS URI.",
                nameof(endpoint));
        }

        return builder.WithMcpTool(name, ReferenceExpression.Create($"{endpointUri.AbsoluteUri}"), options);
    }

    /// <summary>
    /// Adds an MCP tool definition to the Toolbox.
    /// </summary>
    /// <param name="builder">The resource builder for the Toolbox.</param>
    /// <param name="name">The tool name.</param>
    /// <param name="endpoint">The MCP endpoint.</param>
    /// <param name="options">Optional MCP server metadata and approval policy.</param>
    /// <remarks>
    /// During local development, the endpoint must resolve to a Foundry-reachable HTTPS URI, such
    /// as an anonymous development tunnel. A localhost endpoint cannot be reached by the Foundry
    /// data plane. Resource endpoints deployed with public HTTPS ingress can be referenced directly

View on GitHub (pinned to 25830f84bd)