{"record":{"id":"4d4dce35360a4050","repo":"microsoft/aspire","slug":"the-mcp-endpoint-must-be-a-foundry-reachable-absolute-https","errorCode":null,"errorMessage":"The MCP endpoint must be a Foundry-reachable absolute HTTPS URI.","messagePattern":"The MCP endpoint must be a Foundry-reachable absolute HTTPS URI\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs","lineNumber":228,"sourceCode":"    /// </summary>\n    /// <param name=\"builder\">The resource builder for the Toolbox.</param>\n    /// <param name=\"name\">The tool name.</param>\n    /// <param name=\"endpoint\">The MCP endpoint URI.</param>\n    /// <param name=\"options\">Optional MCP server metadata and approval policy.</param>\n    /// <returns>A reference to the <see cref=\"IResourceBuilder{T}\"/> for chaining.</returns>\n    /// <ats-returns>The resource builder.</ats-returns>\n    [AspireExportIgnore(Reason = \"Polyglot app hosts use the union overload instead.\")]\n    public static IResourceBuilder<FoundryToolboxResource> WithMcpTool(\n        this IResourceBuilder<FoundryToolboxResource> builder,\n        string name,\n        string endpoint,\n        FoundryToolboxMcpToolOptions? options = null)\n    {\n        ArgumentException.ThrowIfNullOrEmpty(endpoint);\n        if (!Uri.TryCreate(endpoint, UriKind.Absolute, out var endpointUri) ||\n            !FoundryToolboxMcpToolDefinition.IsFoundryReachableHttpsEndpoint(endpointUri))\n        {\n            throw new ArgumentException(\n                \"The MCP endpoint must be a Foundry-reachable absolute HTTPS URI.\",\n                nameof(endpoint));\n        }\n\n        return builder.WithMcpTool(name, ReferenceExpression.Create($\"{endpointUri.AbsoluteUri}\"), options);\n    }\n\n    /// <summary>\n    /// Adds an MCP tool definition to the Toolbox.\n    /// </summary>\n    /// <param name=\"builder\">The resource builder for the Toolbox.</param>\n    /// <param name=\"name\">The tool name.</param>\n    /// <param name=\"endpoint\">The MCP endpoint.</param>\n    /// <param name=\"options\">Optional MCP server metadata and approval policy.</param>\n    /// <remarks>\n    /// During local development, the endpoint must resolve to a Foundry-reachable HTTPS URI, such\n    /// as an anonymous development tunnel. A localhost endpoint cannot be reached by the Foundry\n    /// data plane. Resource endpoints deployed with public HTTPS ingress can be referenced directly","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs#L210-L246","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Prefix the endpoint with https:// so it parses as an absolute URI.","Ensure the host is reachable over HTTPS by Foundry (public or Azure-network-reachable TLS endpoint).","Use Uri.TryCreate in your own code to validate the string before passing it."],"exampleFix":"// before\nbuilder.WithMcpTool(\"search\", \"my-mcp.example.com/mcp\");\n// after\nbuilder.WithMcpTool(\"search\", \"https://my-mcp.example.com/mcp\");","handlingStrategy":"validation","validationCode":"if (!Uri.TryCreate(endpoint, UriKind.Absolute, out var uri) ||\n    uri.Scheme != Uri.UriSchemeHttps)\n{\n    throw new ArgumentException($\"MCP endpoint '{endpoint}' must be an absolute https:// URL.\", nameof(endpoint));\n}\nbuilder.WithMcpTool(name, uri.AbsoluteUri, options);","typeGuard":"static bool IsHttpsAbsolute(string? s) =>\n    Uri.TryCreate(s, UriKind.Absolute, out var u) && u.Scheme == Uri.UriSchemeHttps;","tryCatchPattern":"try\n{\n    builder.WithMcpTool(name, endpoint, options);\n}\ncatch (ArgumentException ex) when (ex.Message.Contains(\"Foundry-reachable absolute HTTPS URI\"))\n{\n    logger.LogError(ex, \"Invalid MCP endpoint '{Endpoint}' for tool {Tool}.\", endpoint, name);\n    throw;\n}","preventionTips":["Always store MCP endpoints as full https:// URLs in configuration.","Run Uri.TryCreate validation at config-load time, not at API-call time.","Never pass relative paths or http:// URLs for Foundry-reachable MCP tools."],"tags":["validation","url","https","foundry-toolbox"],"backgroundTag":"invalid-url-format","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}