microsoft/aspire · error · InvalidOperationException

MCP server configuration

Error message

MCP server configuration '{configName}' is already registered on Connector Namespace '{builder.Resource.Name}'.

What it means

AddMcpServerConfig rejects duplicate MCP server configuration names within the same Connector Namespace. Config names are compared case-insensitively (OrdinalIgnoreCase) because they map to case-insensitive resource identifiers in Azure. Duplicate registrations would produce ambiguous or conflicting deployed configuration, so the second registration throws.

Solutions

Use a unique name (and unique options.ConfigName) for each AddMcpServerConfig call on the namespace.
Reuse the existing builder returned by the first AddMcpServerConfig call instead of registering again.
Centralize MCP server registration in one place so it cannot be invoked twice with the same name.

Example fix

// before
ns.AddMcpServerConfig("github", githubOptions);
ns.AddMcpServerConfig("GitHub", otherOptions); // throws: case-insensitive duplicate

// after
var github = ns.AddMcpServerConfig("github", githubOptions);
// reuse 'github' builder instead of a second registration

Defensive patterns

Strategy: validation

Validate before calling

bool alreadyRegistered = ns.Resource.McpServerConfigs.Any(c =>
    string.Equals(c.ConfigName, configName, StringComparison.OrdinalIgnoreCase));
if (!alreadyRegistered)
{
    ns.AddMcpServerConfig(name, options);
}

Try / catch

try
{
    var mcp = ns.AddMcpServerConfig(name, options);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("is already registered"))
{
    // reuse the existing config builder instead of registering again
}

Prevention

Register each MCP server config exactly once; keep the returned builder for reuse.
Remember names are case-insensitive — "GitHub" and "github" collide.
Centralize MCP config registration in a single helper/extension.

When it happens

Trigger: Calling AddMcpServerConfig with a name (or options.ConfigName) that case-insensitively matches an already-registered config on the same namespace, e.g. AddMcpServerConfig("github") twice, or "GitHub" after "github".

Common situations: Registering the same MCP server (e.g. GitHub, MCP inspection endpoints) from two extension/helper methods that each call AddMcpServerConfig; copy-pasted builder code using the same name in one namespace.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.ConnectorNamespace/AzureConnectorNamespaceExtensions.cs:474

    /// <param name="name">The Aspire resource name.</param>
    /// <param name="options">The optional MCP server configuration.</param>
    /// <returns>A resource builder for the MCP server configuration.</returns>
    /// <ats-returns>The resource builder.</ats-returns>
    [AspireExport]
    public static IResourceBuilder<AzureConnectorNamespaceMcpServerConfigResource> AddMcpServerConfig(
        this IResourceBuilder<AzureConnectorNamespaceResource> builder,
        [ResourceName] string name,
        AzureConnectorNamespaceMcpServerConfigOptions? options = null)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrWhiteSpace(name);

        var configName = options?.ConfigName ?? name;
        ValidateConnectorResourceName(configName, nameof(options));
        if (builder.Resource.McpServerConfigs.Any(config =>
            string.Equals(config.ConfigName, configName, StringComparison.OrdinalIgnoreCase)))
        {
            throw new InvalidOperationException(
                $"MCP server configuration '{configName}' is already registered on Connector Namespace '{builder.Resource.Name}'.");
        }

        var config = new AzureConnectorNamespaceMcpServerConfigResource(
            name,
            configName,
            options?.Description,
            builder.Resource);
        config.Annotations.Add(ManifestPublishingCallbackAnnotation.Ignore);
        builder.Resource.McpServerConfigs.Add(config);
        return builder.ApplicationBuilder.AddResource(config);
    }

    /// <summary>
    /// Marks a managed MCP server configuration as an existing Azure resource.
    /// </summary>
    /// <param name="builder">The MCP server configuration resource builder.</param>
    /// <returns>The resource builder.</returns>

View on GitHub (pinned to 25830f84bd)