From 32d24bb12f96d6e14d18fa66d5c31dc9742c168a Mon Sep 17 00:00:00 2001
From: "aspire-repo-bot[bot]"
<268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Date: Sun, 15 Nov 2026 20:12:41 +0000
Subject: [PATCH] Document stable WithMcpServer
---
.../content/docs/diagnostics/aspiremcp001.mdx | 6 +++++-
.../src/content/docs/diagnostics/overview.mdx | 2 +-
.../docs/get-started/resource-mcp-servers.mdx | 16 +++++++++-------
3 files changed, 15 insertions(+), 9 deletions(-)
diff --git a/src/frontend/src/content/docs/diagnostics/aspiremcp001.mdx b/src/frontend/src/content/docs/diagnostics/aspiremcp001.mdx
index 77337607e5..336581fec4 100644
--- a/src/frontend/src/content/docs/diagnostics/aspiremcp001.mdx
+++ b/src/frontend/src/content/docs/diagnostics/aspiremcp001.mdx
@@ -4,7 +4,7 @@ seoTitle: "ASPIREMCP001: MCP server types and members are for"
description: Learn what causes the Aspire compiler warning ASPIREMCP001 and how to fix it so your AppHost builds cleanly. Resolve or suppress it to keep your Aspire build.
---
-import { Badge } from '@astrojs/starlight/components';
+import { Aside, Badge } from '@astrojs/starlight/components';
import ApiReference from '@components/ApiReference.astro';
+
+
> MCP server types and members are for evaluation purposes only and are subject to change or removal in future updates. Suppress this diagnostic to proceed.
This diagnostic warning is reported when using the experimental extension method and related Model Context Protocol (MCP) server APIs. These APIs enable Aspire tooling to discover and proxy MCP servers exposed by resources.
diff --git a/src/frontend/src/content/docs/diagnostics/overview.mdx b/src/frontend/src/content/docs/diagnostics/overview.mdx
index b7ee24986a..bb974a54c8 100644
--- a/src/frontend/src/content/docs/diagnostics/overview.mdx
+++ b/src/frontend/src/content/docs/diagnostics/overview.mdx
@@ -58,7 +58,7 @@ The following table lists the possible MSBuild and analyzer warnings and errors
| [ASPIREINTERACTION001](/diagnostics/aspireinteraction001/) | (Experimental) Warning | Interaction service types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIREJAVASCRIPT001](/diagnostics/aspirejavascript001/) | (Experimental) Warning | JavaScript hosting and publishing APIs are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIREHOSTINGPYTHON001](/diagnostics/aspirehostingpython001/) | (Experimental) Error | is for evaluation purposes only and is subject to change or removal in future updates. |
-| [ASPIREMCP001](/diagnostics/aspiremcp001/) | (Experimental) Warning | MCP server types and members are for evaluation purposes only and are subject to change or removal in future updates. |
+| [ASPIREMCP001](/diagnostics/aspiremcp001/) | (Retired) Warning | MCP server types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIREPERSISTENCE001](/diagnostics/aspirepersistence001/) | (Experimental) Error | Resource lifetime types and members are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIREPIPELINES001](/diagnostics/aspirepipelines001/) | (Experimental) Error | Pipeline infrastructure APIs are for evaluation purposes only and are subject to change or removal in future updates. |
| [ASPIREPIPELINES002](/diagnostics/aspirepipelines002/) | (Experimental) Error | Deployment state manager APIs are for evaluation purposes only and are subject to change or removal in future updates. |
diff --git a/src/frontend/src/content/docs/get-started/resource-mcp-servers.mdx b/src/frontend/src/content/docs/get-started/resource-mcp-servers.mdx
index 0e4913375a..9bee4d6026 100644
--- a/src/frontend/src/content/docs/get-started/resource-mcp-servers.mdx
+++ b/src/frontend/src/content/docs/get-started/resource-mcp-servers.mdx
@@ -57,7 +57,7 @@ await builder.build().run();
@@ -97,8 +97,6 @@ You can add any container that implements the MCP protocol as an MCP-enabled res
```csharp title="AppHost.cs"
-#pragma warning disable ASPIREMCP001
-
var builder = DistributedApplication.CreateBuilder(args);
// Add a custom MCP server container
@@ -126,14 +124,18 @@ await builder.build().run();
-The MCP annotation method accepts an optional path and endpoint name:
+`WithMcpServer` declares an MCP server that already exists on the resource. It adds metadata that Aspire tooling uses for discovery and proxying; it doesn't create an endpoint, start a server, or configure transport or authentication. The server must implement MCP at the declared URL.
+
+The method accepts an optional path and endpoint name:
-- With no arguments, it uses the default HTTP endpoint at `/mcp`.
-- To use a named endpoint at a different path, pass the path and endpoint name, such as `/sse` and `https`.
+- With no arguments, it uses the `https` endpoint if one exists, otherwise the `http` endpoint, at the `/mcp` path. Endpoint names are matched case-insensitively, regardless of declaration order.
+- To use any other endpoint, pass its name with `endpointName`, even when it uses HTTPS.
+- A path without a leading slash gets one added. A null or empty path uses the endpoint's base URL, and trailing slashes are kept.
+- A missing endpoint selection fails when the resolver consumes the declaration, not when you call `WithMcpServer`.
## See also
- [Use AI coding agents](/get-started/ai-coding-agents/) — set up your project for AI agents
- [Aspire MCP server](/get-started/aspire-mcp-server/) — the built-in MCP server tools
-- [ASPIREMCP001 diagnostic](/diagnostics/aspiremcp001/) — experimental MCP server API warning
+- [ASPIREMCP001 diagnostic](/diagnostics/aspiremcp001/) — retired MCP server API warning
- [ASPIREPOSTGRES001 diagnostic](/diagnostics/aspirepostgres001/) — experimental PostgreSQL MCP warning