microsoft/aspire · error · DistributedApplicationException

Could not create MCP server for resource

Error message

Could not create MCP server for resource '{resource.Name}' as no endpoint was found with name '{endpointName}'.

What it means

WithMcpServer resolves the endpoint that will host the MCP server at annotation-evaluation time. When an explicit endpointName was supplied and no endpoint on the resource matches that name (case-insensitive per EndpointAnnotationName comparison), it throws DistributedApplicationException. This fails fast because the MCP server cannot be exposed without a valid endpoint reference.

Solutions

Declare a matching endpoint on the resource, e.g. .WithHttpEndpoint(name: "<endpointName>") or pass the name of an existing endpoint.
Omit endpointName to let WithMcpServer pick the first 'https' or 'http' endpoint automatically.
List the resource's endpoints (WithEndpoint/WithHttpEndpoint calls) and align the endpointName spelling exactly.

Example fix

// before
var api = builder.AddProject<Projects.MyApi>("api")
    .WithMcpServer(endpointName: "apiv2"); // no such endpoint

// after
var api = builder.AddProject<Projects.MyApi>("api")
    .WithHttpEndpoint(name: "apiv2")
    .WithMcpServer(endpointName: "apiv2");

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the named endpoint exists before WithMcpServer resolves its annotation callback.
// Endpoint names come from WithEndpoint/WithHttpEndpoint(name: ...) declarations.
var endpointNames = new[] { "https", "http", "apiv2" }; // names you declared
if (!endpointNames.Contains(endpointName, StringComparer.OrdinalIgnoreCase))
{
    throw new ArgumentException($"Endpoint '{endpointName}' is not declared on the resource.");
}

Try / catch

try
{
    builder.WithMcpServer(endpointName: "apiv2");
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("no endpoint was found with name"))
{
    logger.LogError(ex, "Declare the endpoint via WithHttpEndpoint(name:) before referencing it.");
    throw;
}

Prevention

Keep endpoint names in constants shared between WithEndpoint and WithMcpServer calls.
Omit endpointName when an https/http endpoint already exists.
Check endpoint declarations on the resource whenever renaming endpoints.
Remember the match is on the endpoint NAME, not the URL scheme, unless they coincide.

When it happens

Trigger: Calling builder.AddProject(...).WithMcpServer(endpointName: "someEndpoint") where the project/container resource has no WithEndpoint/WithHttpEndpoint/WithHttpsEndpoint declaring an endpoint literally named 'someEndpoint' (note: the name compared is the endpoint name, not the URL scheme unless they coincide).

Common situations: Typo in the endpoint name; assuming the callback receives a scheme like 'https' when the endpoint was created with a custom name; endpoint declared on a different resource; renaming an endpoint without updating WithMcpServer callers.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs:62

        this IResourceBuilder<T> builder,
        string? path = "/mcp",
        [EndpointName] string? endpointName = null)
        where T : IResourceWithEndpoints
    {
        ArgumentNullException.ThrowIfNull(builder);

        return builder.WithAnnotation(new McpServerEndpointAnnotation(async (resource, cancellationToken) =>
        {
            var endpoints = resource.GetEndpoints();
            EndpointReference? endpoint = null;

            if (endpointName is not null)
            {
                endpoint = endpoints.FirstOrDefault(e => string.Equals(e.EndpointName, endpointName, StringComparisons.EndpointAnnotationName));

                if (endpoint is null)
                {
                    throw new DistributedApplicationException(
                        $"Could not create MCP server for resource '{resource.Name}' as no endpoint was found with name '{endpointName}'.");
                }
            }
            else
            {
                foreach (var scheme in s_httpSchemes)
                {
                    endpoint = endpoints.FirstOrDefault(e => string.Equals(e.EndpointName, scheme, StringComparisons.EndpointAnnotationName));
                    if (endpoint is not null)
                    {
                        break;
                    }
                }

                if (endpoint is null)
                {
                    throw new DistributedApplicationException(
                        $"Could not create MCP server for resource '{resource.Name}' as no endpoint was found matching one of the specified names: {string.Join(", ", s_httpSchemes)}");

View on GitHub (pinned to 25830f84bd)