microsoft/aspire · error · InvalidOperationException

MCP endpoint for resource

Error message

MCP endpoint for resource '{resourceName}' is not available.

What it means

This error is thrown by the auxiliary backchannel RPC target when resolving an MCP endpoint annotation for a resource succeeded, but the annotation's EndpointUrlResolver returned null. It means the resource declares an MCP endpoint, but no concrete URL could be resolved at the time of the call (e.g. the endpoint is not running or not yet allocated).

Solutions

Verify the resource is running and has reached a state where its MCP endpoint URL is allocated before invoking tools.
Check that the EndpointUrlResolver on the McpEndpointAnnotation returns the correct URL and does not silently return null.
Wait for the resource's endpoint/event indicating it is listening, then retry the tool invocation.
Inspect the resource in the dashboard to confirm the MCP endpoint is present and healthy.

Example fix

// before: call immediately after adding resource
await rpcTarget.InvokeMcpToolAsync("myresource", "mytool", args);
// after: wait for the resource to be running and endpoint resolved
await app.ResourceNotifications.WaitForResourceHealthyAsync("myresource");
await rpcTarget.InvokeMcpToolAsync("myresource", "mytool", args);

Defensive patterns

Strategy: validation

Validate before calling

// Before invoking, ensure the resource is running and its MCP endpoint resolves
var annotation = resource.Annotations.OfType<McpEndpointAnnotation>().SingleOrDefault();
if (annotation is null) throw new InvalidOperationException("Resource has no MCP endpoint annotation.");
var url = await annotation.EndpointUrlResolver(resource, ct);
if (url is null) throw new InvalidOperationException("MCP endpoint URL not yet available; wait for the resource to start.");

Type guard

bool CanInvokeMcpTool(IResource resource) =>
    resource.Annotations.OfType<McpEndpointAnnotation>().Any();

Prevention

Wait for the resource to be healthy/running before invoking MCP tools.
Verify the endpoint URL is allocated in the dashboard before tool calls.
Review any custom EndpointUrlResolver for paths that return null.

When it happens

Trigger: Calling the backchannel RPC method that invokes an MCP tool when the resource's MCP endpoint annotation exists but EndpointUrlResolver returns null — typically because the resource is not running, the endpoint has no allocated URL yet, or the resolver is misconfigured.

Common situations: Invoking an MCP tool against a resource that is stopped or still starting; calling before the endpoint URL has been assigned; a custom EndpointUrlResolver that fails to produce a value.

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/a5aa8ba4f63098a9. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting/Backchannel/AuxiliaryBackchannelRpcTarget.cs:1803

        var resource = appModel.Resources
            .OfType<IResourceWithEndpoints>()
            .FirstOrDefault(r => string.Equals(r.Name, resourceName, StringComparisons.ResourceName));

        if (resource is null)
        {
            throw new InvalidOperationException($"Resource '{resourceName}' not found.");
        }

        if (!resource.TryGetLastAnnotation<McpServerEndpointAnnotation>(out var annotation))
        {
            throw new InvalidOperationException($"Resource '{resourceName}' does not have an MCP endpoint annotation.");
        }

        var endpointUri = await annotation.EndpointUrlResolver(resource, cancellationToken).ConfigureAwait(false);
        if (endpointUri is null)
        {
            throw new InvalidOperationException($"MCP endpoint for resource '{resourceName}' is not available.");
        }

        var transport = CreateHttpClientTransport(endpointUri);

        McpClient? mcpClient = null;
        try
        {
            mcpClient = await McpClient.CreateAsync(transport, cancellationToken: cancellationToken).ConfigureAwait(false)
                ?? throw new InvalidOperationException("Failed to create MCP client.");

            if (logger.IsEnabled(LogLevel.Debug))
            {
                logger.LogDebug("Invoking tool {Name} with arguments {Arguments}", toolName, JsonSerializer.Serialize(arguments));
            }

            var result = await mcpClient.CallToolAsync(toolName, arguments, cancellationToken: cancellationToken).ConfigureAwait(false);

            if (logger.IsEnabled(LogLevel.Debug))

View on GitHub (pinned to 25830f84bd)