diff --git a/docs/list-of-diagnostics.md b/docs/list-of-diagnostics.md
index 670d431229d..552d3ca321b 100644
--- a/docs/list-of-diagnostics.md
+++ b/docs/list-of-diagnostics.md
@@ -41,6 +41,12 @@ Connection-string physical-name metadata (`ConnectionStringEnvironmentVariableNa
`ConnectionStringReference.EnvironmentVariableNames`) is stable and no longer produces
`ASPIRECONNECTIONSTRINGS001`. Existing suppressions of that diagnostic can be removed.
+### Retired Experimental API Warnings
+
+| Diagnostic ID | Description | Location |
+| ------------- | ----------- | -------- |
+| `ASPIREMCP001` | MCP endpoint declaration via `WithMcpServer` is stable and no longer requires suppression. This declares an existing server for Aspire tooling discovery and proxying; it does not implement or configure an MCP transport. | [src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs](../src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs) |
+
## Analyzer Warnings
| Diagnostic ID | Severity | Description | Location |
diff --git a/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs b/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs
index ee59495d558..c9f5eaddaaf 100644
--- a/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs
+++ b/src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs
@@ -1,7 +1,6 @@
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
-#pragma warning disable ASPIREMCP001
#pragma warning disable ASPIRETERMINAL001
using System.Globalization;
diff --git a/src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs b/src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs
index 146c0db1836..d523218dc8f 100644
--- a/src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs
+++ b/src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs
@@ -1,7 +1,6 @@
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
-using System.Diagnostics.CodeAnalysis;
using Aspire.Hosting.ApplicationModel;
namespace Aspire.Hosting;
@@ -18,13 +17,20 @@ public static class McpServerResourceBuilderExtensions
///
/// The resource type.
/// The resource builder.
- /// An optional path to append to the endpoint URL when forming the MCP server address. Defaults to "/mcp".
- /// An optional name of the endpoint that hosts the MCP server. If not specified, defaults to the first HTTPS or HTTP endpoint.
+ /// An optional path to append to the endpoint URL when forming the MCP server address. Defaults to "/mcp".
+ /// A leading slash is added if missing. A null or empty value uses the endpoint URL without an additional path.
+ /// An optional name of the endpoint that hosts the MCP server. If not specified, selects the endpoint
+ /// named https, falling back to the endpoint named http. Names are matched case-insensitively;
+ /// endpoints with other names must be selected explicitly, regardless of their URI scheme.
/// A reference to the for chaining additional configuration.
/// The resource builder.
///
/// This method adds an to the resource, enabling the Aspire tooling
/// to discover and proxy the MCP server exposed by the resource.
+ /// It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ /// The resource must already expose an MCP server at the selected endpoint and path.
+ /// Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ /// A missing selected endpoint causes resolution to throw a .
///
///
/// Mark a resource as hosting an MCP server using the default endpoint:
@@ -38,7 +44,6 @@ public static class McpServerResourceBuilderExtensions
/// .WithMcpServer("/sse", endpointName: "https");
///
///
- [Experimental("ASPIREMCP001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
[AspireExport]
public static IResourceBuilder WithMcpServer(
this IResourceBuilder builder,
diff --git a/tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.go b/tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.go
index 3eadff70216..29adfab599c 100644
--- a/tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.go
+++ b/tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.go
@@ -3341,16 +3341,17 @@ type Aspire_Hosting_CodeGeneration_Go_TestsTestVaultResource interface {
//
// This method adds an McpServerEndpointAnnotation to the resource, enabling the
// Aspire tooling to discover and proxy the MCP server exposed by the resource.
+ // It does not create an endpoint, start an MCP server, or configure its
+ // transport or authentication. The resource must already expose an MCP server
+ // at the selected endpoint and path. Endpoint selection and URL resolution
+ // occur when tooling consumes the annotation, not when this method is called. A
+ // missing selected endpoint causes resolution to throw a
+ // DistributedApplicationException.
//
// Parameters:
// - options: Optional parameters; see [WithMcpServerOption].
//
// Returns: The resource builder.
- //
- // # Experimental
- //
- // Notice: This API is EXPERIMENTAL and may be changed or removed in a later
- // release.
WithMcpServer(options ...WithMcpServerOption) Aspire_Hosting_CodeGeneration_Go_TestsTestVaultResource
// WithMergeEndpoint configures a named endpoint
@@ -7470,16 +7471,17 @@ type CSharpAppResource interface {
//
// This method adds an McpServerEndpointAnnotation to the resource, enabling the
// Aspire tooling to discover and proxy the MCP server exposed by the resource.
+ // It does not create an endpoint, start an MCP server, or configure its
+ // transport or authentication. The resource must already expose an MCP server
+ // at the selected endpoint and path. Endpoint selection and URL resolution
+ // occur when tooling consumes the annotation, not when this method is called. A
+ // missing selected endpoint causes resolution to throw a
+ // DistributedApplicationException.
//
// Parameters:
// - options: Optional parameters; see [WithMcpServerOption].
//
// Returns: The resource builder.
- //
- // # Experimental
- //
- // Notice: This API is EXPERIMENTAL and may be changed or removed in a later
- // release.
WithMcpServer(options ...WithMcpServerOption) CSharpAppResource
// WithMergeEndpoint configures a named endpoint
@@ -14900,16 +14902,17 @@ type ContainerResource interface {
//
// This method adds an McpServerEndpointAnnotation to the resource, enabling the
// Aspire tooling to discover and proxy the MCP server exposed by the resource.
+ // It does not create an endpoint, start an MCP server, or configure its
+ // transport or authentication. The resource must already expose an MCP server
+ // at the selected endpoint and path. Endpoint selection and URL resolution
+ // occur when tooling consumes the annotation, not when this method is called. A
+ // missing selected endpoint causes resolution to throw a
+ // DistributedApplicationException.
//
// Parameters:
// - options: Optional parameters; see [WithMcpServerOption].
//
// Returns: The resource builder.
- //
- // # Experimental
- //
- // Notice: This API is EXPERIMENTAL and may be changed or removed in a later
- // release.
WithMcpServer(options ...WithMcpServerOption) ContainerResource
// WithMergeEndpoint configures a named endpoint
@@ -21142,16 +21145,17 @@ type DotnetToolResource interface {
//
// This method adds an McpServerEndpointAnnotation to the resource, enabling the
// Aspire tooling to discover and proxy the MCP server exposed by the resource.
+ // It does not create an endpoint, start an MCP server, or configure its
+ // transport or authentication. The resource must already expose an MCP server
+ // at the selected endpoint and path. Endpoint selection and URL resolution
+ // occur when tooling consumes the annotation, not when this method is called. A
+ // missing selected endpoint causes resolution to throw a
+ // DistributedApplicationException.
//
// Parameters:
// - options: Optional parameters; see [WithMcpServerOption].
//
// Returns: The resource builder.
- //
- // # Experimental
- //
- // Notice: This API is EXPERIMENTAL and may be changed or removed in a later
- // release.
WithMcpServer(options ...WithMcpServerOption) DotnetToolResource
// WithMergeEndpoint configures a named endpoint
@@ -26330,16 +26334,17 @@ type ExecutableResource interface {
//
// This method adds an McpServerEndpointAnnotation to the resource, enabling the
// Aspire tooling to discover and proxy the MCP server exposed by the resource.
+ // It does not create an endpoint, start an MCP server, or configure its
+ // transport or authentication. The resource must already expose an MCP server
+ // at the selected endpoint and path. Endpoint selection and URL resolution
+ // occur when tooling consumes the annotation, not when this method is called. A
+ // missing selected endpoint causes resolution to throw a
+ // DistributedApplicationException.
//
// Parameters:
// - options: Optional parameters; see [WithMcpServerOption].
//
// Returns: The resource builder.
- //
- // # Experimental
- //
- // Notice: This API is EXPERIMENTAL and may be changed or removed in a later
- // release.
WithMcpServer(options ...WithMcpServerOption) ExecutableResource
// WithMergeEndpoint configures a named endpoint
@@ -37926,16 +37931,17 @@ type ProjectResource interface {
//
// This method adds an McpServerEndpointAnnotation to the resource, enabling the
// Aspire tooling to discover and proxy the MCP server exposed by the resource.
+ // It does not create an endpoint, start an MCP server, or configure its
+ // transport or authentication. The resource must already expose an MCP server
+ // at the selected endpoint and path. Endpoint selection and URL resolution
+ // occur when tooling consumes the annotation, not when this method is called. A
+ // missing selected endpoint causes resolution to throw a
+ // DistributedApplicationException.
//
// Parameters:
// - options: Optional parameters; see [WithMcpServerOption].
//
// Returns: The resource builder.
- //
- // # Experimental
- //
- // Notice: This API is EXPERIMENTAL and may be changed or removed in a later
- // release.
WithMcpServer(options ...WithMcpServerOption) ProjectResource
// WithMergeEndpoint configures a named endpoint
@@ -43978,16 +43984,17 @@ type TestDatabaseResource interface {
//
// This method adds an McpServerEndpointAnnotation to the resource, enabling the
// Aspire tooling to discover and proxy the MCP server exposed by the resource.
+ // It does not create an endpoint, start an MCP server, or configure its
+ // transport or authentication. The resource must already expose an MCP server
+ // at the selected endpoint and path. Endpoint selection and URL resolution
+ // occur when tooling consumes the annotation, not when this method is called. A
+ // missing selected endpoint causes resolution to throw a
+ // DistributedApplicationException.
//
// Parameters:
// - options: Optional parameters; see [WithMcpServerOption].
//
// Returns: The resource builder.
- //
- // # Experimental
- //
- // Notice: This API is EXPERIMENTAL and may be changed or removed in a later
- // release.
WithMcpServer(options ...WithMcpServerOption) TestDatabaseResource
// WithMergeEndpoint configures a named endpoint
@@ -48459,16 +48466,17 @@ type TestRedisResource interface {
//
// This method adds an McpServerEndpointAnnotation to the resource, enabling the
// Aspire tooling to discover and proxy the MCP server exposed by the resource.
+ // It does not create an endpoint, start an MCP server, or configure its
+ // transport or authentication. The resource must already expose an MCP server
+ // at the selected endpoint and path. Endpoint selection and URL resolution
+ // occur when tooling consumes the annotation, not when this method is called. A
+ // missing selected endpoint causes resolution to throw a
+ // DistributedApplicationException.
//
// Parameters:
// - options: Optional parameters; see [WithMcpServerOption].
//
// Returns: The resource builder.
- //
- // # Experimental
- //
- // Notice: This API is EXPERIMENTAL and may be changed or removed in a later
- // release.
WithMcpServer(options ...WithMcpServerOption) TestRedisResource
// WithMergeEndpoint configures a named endpoint
@@ -53522,10 +53530,13 @@ func (o *WithHttpHealthCheckOptions) ToMap() map[string]any {
// WithMcpServerOptions carries optional parameters for WithMcpServer.
type WithMcpServerOptions struct {
// Path is an optional path to append to the endpoint URL when forming the MCP
- // server address. Defaults to "/mcp".
+ // server address. Defaults to "/mcp". A leading slash is added if missing. A
+ // null or empty value uses the endpoint URL without an additional path.
Path *string `json:"path,omitempty"`
// EndpointName is an optional name of the endpoint that hosts the MCP server.
- // If not specified, defaults to the first HTTPS or HTTP endpoint.
+ // If not specified, selects the endpoint named https, falling back to the
+ // endpoint named http. Names are matched case-insensitively; endpoints with
+ // other names must be selected explicitly, regardless of their URI scheme.
EndpointName *string `json:"endpointName,omitempty"`
}
diff --git a/tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.ts b/tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.ts
index 2119996ed6b..3ada7b860e0 100644
--- a/tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.ts
+++ b/tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.ts
@@ -1923,9 +1923,9 @@ export interface WithImageOptions {
}
export interface WithMcpServerOptions {
- /** An optional path to append to the endpoint URL when forming the MCP server address. Defaults to `"/mcp"`. */
+ /** An optional path to append to the endpoint URL when forming the MCP server address. Defaults to `"/mcp"`. A leading slash is added if missing. A null or empty value uses the endpoint URL without an additional path. */
path?: string;
- /** An optional name of the endpoint that hosts the MCP server. If not specified, defaults to the first HTTPS or HTTP endpoint. */
+ /** An optional name of the endpoint that hosts the MCP server. If not specified, selects the endpoint named `https`, falling back to the endpoint named `http`. Names are matched case-insensitively; endpoints with other names must be selected explicitly, regardless of their URI scheme. */
endpointName?: string;
}
@@ -15536,9 +15536,12 @@ export interface ContainerResource {
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): ContainerResourcePromise;
/**
@@ -16406,9 +16409,12 @@ export interface ContainerResourcePromise extends PromiseLike
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): ContainerResourcePromise;
/**
@@ -17626,9 +17632,12 @@ class ContainerResourceImpl extends ResourceBuilderBase
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): ContainerResourcePromise {
const path = options?.path;
@@ -20136,9 +20145,12 @@ export interface CSharpAppResource {
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): CSharpAppResourcePromise;
/**
@@ -20846,9 +20858,12 @@ export interface CSharpAppResourcePromise extends PromiseLike
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): CSharpAppResourcePromise;
/**
@@ -21607,9 +21622,12 @@ class CSharpAppResourceImpl extends ResourceBuilderBase
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): CSharpAppResourcePromise {
const path = options?.path;
@@ -24240,9 +24258,12 @@ export interface DotnetToolResource {
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): DotnetToolResourcePromise;
/**
@@ -24986,9 +25007,12 @@ export interface DotnetToolResourcePromise extends PromiseLike {
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): ProjectResourcePromise;
/**
@@ -38634,9 +38676,12 @@ class ProjectResourceImpl extends ResourceBuilderBase imp
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): ProjectResourcePromise {
const path = options?.path;
@@ -41386,9 +41431,12 @@ export interface TestDatabaseResource {
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): TestDatabaseResourcePromise;
/**
@@ -42256,9 +42304,12 @@ export interface TestDatabaseResourcePromise extends PromiseLike
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): TestRedisResourcePromise;
/**
@@ -48422,9 +48482,12 @@ class TestRedisResourceImpl extends ResourceBuilderBase
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): TestRedisResourcePromise {
const path = options?.path;
@@ -51441,9 +51504,12 @@ export interface TestVaultResource {
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): TestVaultResourcePromise;
/**
@@ -52313,9 +52379,12 @@ export interface TestVaultResourcePromise extends PromiseLike
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): TestVaultResourcePromise;
/**
@@ -53534,9 +53603,12 @@ class TestVaultResourceImpl extends ResourceBuilderBase
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): TestVaultResourcePromise {
const path = options?.path;
@@ -58988,9 +59060,12 @@ export interface ResourceWithEndpoints {
*
* This method adds an `McpServerEndpointAnnotation` to the resource, enabling the Aspire tooling
* to discover and proxy the MCP server exposed by the resource.
+ * It does not create an endpoint, start an MCP server, or configure its transport or authentication.
+ * The resource must already expose an MCP server at the selected endpoint and path.
+ * Endpoint selection and URL resolution occur when tooling consumes the annotation, not when this method is called.
+ * A missing selected endpoint causes resolution to throw a `DistributedApplicationException`.
* @param options Additional options.
* @returns The resource builder.
- * @experimental
*/
withMcpServer(options?: WithMcpServerOptions): ResourceWithEndpointsPromise;
/**
@@ -59089,9 +59164,12 @@ export interface ResourceWithEndpointsPromise extends PromiseLike
+ {
+ e.UriScheme = "http";
+ e.AllocatedEndpoint = new AllocatedEndpoint(e, "localhost", 8080);
+ })
.WithEndpoint("https", e =>
{
e.UriScheme = "https";
e.AllocatedEndpoint = new AllocatedEndpoint(e, "localhost", 8443);
})
- .WithHttpEndpoint(name: "http")
.WithMcpServer();
using var app = await appBuilder.BuildAsync();
@@ -112,8 +114,13 @@ public async Task WithMcpServer_ResolvesDefaultMcpPath()
Assert.Equal("http://localhost:8080/mcp", resolvedUri!.ToString());
}
- [Fact]
- public async Task WithMcpServer_ResolvesCustomPath()
+ [Theory]
+ [InlineData("/sse", "http://localhost:8080/sse")]
+ [InlineData("custom/path", "http://localhost:8080/custom/path")]
+ [InlineData("", "http://localhost:8080/")]
+ [InlineData("/", "http://localhost:8080/")]
+ [InlineData("/mcp/", "http://localhost:8080/mcp/")]
+ public async Task WithMcpServer_ResolvesCustomPath(string path, string expectedUrl)
{
using var appBuilder = TestDistributedApplicationBuilder.Create();
@@ -123,7 +130,7 @@ public async Task WithMcpServer_ResolvesCustomPath()
e.UriScheme = "http";
e.AllocatedEndpoint = new AllocatedEndpoint(e, "localhost", 8080);
})
- .WithMcpServer("/sse", endpointName: "http");
+ .WithMcpServer(path, endpointName: "http");
using var app = await appBuilder.BuildAsync();
@@ -134,7 +141,51 @@ public async Task WithMcpServer_ResolvesCustomPath()
var resolvedUri = await mcpAnnotation.EndpointUrlResolver(resource, CancellationToken.None);
Assert.NotNull(resolvedUri);
- Assert.Equal("http://localhost:8080/sse", resolvedUri!.ToString());
+ Assert.Equal(expectedUrl, resolvedUri!.ToString());
+ }
+
+ [Theory]
+ [InlineData("management")]
+ [InlineData("MANAGEMENT")]
+ public async Task WithMcpServer_ResolvesExplicitlyNamedEndpoint(string endpointName)
+ {
+ using var appBuilder = TestDistributedApplicationBuilder.Create();
+
+ var container = appBuilder.AddContainer("app", "image")
+ .WithHttpEndpoint(name: "https")
+ .WithEndpoint("management", e =>
+ {
+ e.UriScheme = "http";
+ e.AllocatedEndpoint = new AllocatedEndpoint(e, "localhost", 8080);
+ })
+ .WithMcpServer(endpointName: endpointName);
+
+ var annotation = Assert.Single(container.Resource.Annotations.OfType());
+ var resolvedUri = await annotation.EndpointUrlResolver(container.Resource, CancellationToken.None);
+
+ Assert.Equal(new Uri("http://localhost:8080/mcp"), resolvedUri);
+ }
+
+ [Theory]
+ [InlineData(null, "Could not create MCP server for resource 'app' as no endpoint was found matching one of the specified names: https, http")]
+ [InlineData("missing", "Could not create MCP server for resource 'app' as no endpoint was found with name 'missing'.")]
+ public async Task WithMcpServer_ThrowsWhenSelectedEndpointDoesNotExist(string? endpointName, string expectedMessage)
+ {
+ using var appBuilder = TestDistributedApplicationBuilder.Create();
+
+ var container = appBuilder.AddContainer("app", "image")
+ .WithEndpoint("management", e =>
+ {
+ e.UriScheme = "https";
+ e.AllocatedEndpoint = new AllocatedEndpoint(e, "localhost", 8443);
+ })
+ .WithMcpServer(endpointName: endpointName);
+
+ var annotation = Assert.Single(container.Resource.Annotations.OfType());
+ var exception = await Assert.ThrowsAsync(
+ () => annotation.EndpointUrlResolver(container.Resource, CancellationToken.None));
+
+ Assert.Equal(expectedMessage, exception.Message);
}
[Fact]