Skip to content

Graduate MCP endpoint declaration to stable - #22158

Merged
Maddy Montaquila (maddymontaquila) merged 4 commits into
release/17.0from
maddymontaquila/stabilize-mcp-endpoint-api
Nov 15, 2026
Merged

Maddy Montaquila (maddymontaquila) merged 4 commits into
release/17.0from
maddymontaquila/stabilize-mcp-endpoint-api

Conversation

@maddymontaquila

@maddymontaquila Maddy Montaquila (maddymontaquila) commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Description

AppHosts can declare an existing MCP server with WithMcpServer without suppressing ASPIREMCP001. This graduates the endpoint declaration helper only; it retains the API, its [AspireExport], and all runtime behavior. It does not graduate a transport implementation or the separate PostgreSQL MCP integration.

Removes the experimental attribute and the two directly related suppressions, documents the precise contract, records the retired diagnostic, and strengthens endpoint/path tests. Generated TypeScript and Go test snapshots now reflect the stable API and updated documentation. Generated api/*.cs and ATS release baselines are untouched. No new dependencies.

Original API contributor: David Fowler (@davidfowl) — introduced in #14618, with the initial Copilot-authored commit crediting him as co-author and his follow-up implementation commit establishing the current endpoint-selection shape. Mentioning for awareness, not assigning a review or asserting approval to graduate.

Fixes # (issue)

Contract review

Preserves the existing declaration contract rather than broadening it:

  • Default selection is case-insensitive endpoint name matching: https, then http, independent of declaration order. Arbitrary names require endpointName, even when their scheme is HTTPS. Missing selections fail during resolver consumption, not registration.
  • Paths default to /mcp; a missing leading slash is added. Null/empty uses the base endpoint URL, and trailing path slashes are retained.
  • Registration adds metadata consumed by Aspire tooling for discovery/proxying. It does not create an endpoint, start a server, or configure transport/authentication. The existing server must implement MCP at the declared URL; declaration alone does not guarantee successful discovery.

These boundaries are grounded in the current implementation, dedicated tests, original introducing PR, and backchannel consumers. No claim is made about upstream protocol GA or maintainer graduation approval. Open PR searches for ASPIREMCP001, WithMcpServer, and MCP stabilization found no duplicate.

User-facing usage

For an existing resource api that exposes an MCP server on its http endpoint:

api.WithMcpServer("/mcp", endpointName: "http");

The existing generated TypeScript shape is retained, without @experimental:

await api.withMcpServer({ path: "/mcp", endpointName: "http" });

Release branch replay and conflict resolution

Targets release/17.0. Replayed only the three intended stabilization/snapshot commits after the verified original-main fork point 793dfe6e254fe050af24cb7bcfba214066dcaab8 onto release commit 9a97ab889bfb731de74ead0280be279ffdd000bf; unrelated main history is excluded.

Subsequently merged release commit bcfa151cdca6d0a573f22d5d9c23f9c727cb3b2f and resolved conflicts in diagnostic documentation and the Go snapshot. Preserved the release connection-string diagnostic explanation and its now-current ...WithMcpServerOption functional-option signature, retaining the stable MCP documentation and removing only the applicable experimental notices. The earlier replay had retained the pointer-option signature used by release at that time. No runtime implementation adaptations or new features were needed. The PR remains scoped to six changed files.

Validation on release/17.0

The following commands passed again on conflict-resolution head a4095d31cc6a8149cf8c3d097fa48292feba9417:

  • ./restore.sh — passed; zero warnings and zero errors.
  • dotnet test --project tests/Aspire.Hosting.Tests/Aspire.Hosting.Tests.csproj --no-launch-profile -- --filter-class '*.WithMcpServerTests' --filter-class '*.McpServerEndpointAnnotationTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true' — passed, 31 tests.
  • dotnet test --project tests/Aspire.Hosting.PostgreSQL.Tests/Aspire.Hosting.PostgreSQL.Tests.csproj --no-launch-profile -- --filter-class '*.PostgresMcpBuilderTests' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true' — passed, 5 tests.
  • dotnet test --project tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests.csproj --no-launch-profile -- --filter-method '*.TwoPassScanning_GeneratesWithEnvironmentOnTestRedisBuilder' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true' — passed, 1 test.
  • dotnet test --project tests/Aspire.Hosting.CodeGeneration.Go.Tests/Aspire.Hosting.CodeGeneration.Go.Tests.csproj --no-launch-profile -- --filter-method '*.TwoPassScanning_GeneratesWithEnvironmentOnTestRedisBuilder' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true' — passed, 1 test.
  • dotnet test --project tests/Aspire.Hosting.CodeGeneration.Java.Tests/Aspire.Hosting.CodeGeneration.Java.Tests.csproj --no-launch-profile -- --filter-method '*.TwoPassScanning_GeneratesWithEnvironmentOnTestRedisBuilder' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true' — passed, 1 test.
  • dotnet test --project tests/Aspire.Hosting.CodeGeneration.Python.Tests/Aspire.Hosting.CodeGeneration.Python.Tests.csproj --no-launch-profile -- --filter-method '*.TwoPassScanning_GeneratesWithEnvironmentOnTestRedisBuilder' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true' — passed, 1 test.
  • dotnet test --project tests/Aspire.Hosting.CodeGeneration.Rust.Tests/Aspire.Hosting.CodeGeneration.Rust.Tests.csproj --no-launch-profile -- --filter-method '*.TwoPassScanning_GeneratesWithEnvironmentOnTestRedisBuilder' --filter-not-trait 'quarantined=true' --filter-not-trait 'outerloop=true' — passed, 1 test.
  • git diff --check origin/release/17.0...HEAD — passed.

Total current release passing tests: 41. All snapshot tests passed on their first run, without further snapshot changes. The previous release replay at b6b8fa54bedbdbb450b33e4d104b150d729efe77 also passed the same 41 tests; its restore had 13 existing dependency vulnerability warnings and zero errors. No live MCP transport/authentication or deployment behavior was changed or tested.

Previous main-branch validation

Before replaying onto release, the same test commands passed 41 tests on main-based head d810c2bd15c412aa31d22e21a419864f394b16c3. The initial main-based TypeScript and Go runs intentionally failed while Verify refreshed the expected MCP-only snapshot changes; identical reruns passed after review. Those historical results are separate from the release validation above.

Checklist

  • Is this feature complete?
    • Yes. Ready to ship.
    • No. Follow-up changes expected.
  • Are you including unit tests for the changes and scenario tests if relevant?
    • Yes
    • No
  • Did you add public API?
    • Yes
      • If yes, did you have an API Review for it?
        • Yes
        • No
      • Did you add <remarks /> and <code /> elements on your triple slash comments?
        • Yes
        • No
    • No
  • Does the change make any security assumptions or guarantees?
    • Yes
      • If yes, have you done a threat model and had a security review?
        • Yes
        • No
    • No

@github-actions

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 22158

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 22158"

@github-actions github-actions Bot added the area-integrations Issues pertaining to Aspire Integrations packages label Nov 11, 2026
@aspire-repo-bot
aspire-repo-bot Bot requested a balanced review from Copilot November 11, 2026 19:19

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

There are no active review issues blocking the WithMcpServer API graduation.

No open issues 🎉

What changed in this PR

Graduates Aspire’s WithMcpServer endpoint declaration helper to stable while preserving its API, export, and runtime behavior. MCP transport implementations and the separate PostgreSQL MCP integration remain outside this graduation.

Changes:

  • Removes the experimental marker and related suppressions, and records ASPIREMCP001 as retired.
  • Clarifies endpoint selection, path handling, deferred resolution, and declaration-only behavior.
  • Expands endpoint/path tests and updates TypeScript and Go snapshots to reflect the stable API documentation.
File Description
tests/​Aspire.Hosting.Tests/​WithMcpServerTests.cs Removes suppression and expands endpoint selection, path, and failure coverage.
tests/​Aspire.Hosting.CodeGeneration.TypeScript.Tests/​Snapshots/​TwoPassScanningGeneratedAspire.verified.ts Updates generated documentation and removes experimental notices.
tests/​Aspire.Hosting.CodeGeneration.Go.Tests/​Snapshots/​TwoPassScanningGeneratedAspire.verified.go Updates generated documentation and removes experimental notices.
src/​Aspire.Hosting/​McpServerResourceBuilderExtensions.cs Removes the experimental attribute and documents the existing contract.
src/​Aspire.Hosting.PostgreSQL/​PostgresBuilderExtensions.cs Removes the obsolete ASPIREMCP001 suppression.
docs/​list-of-diagnostics.md Records the retired diagnostic and its limited graduation scope.

Review effort: Balanced

@github-actions

This comment has been minimized.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

Maddy Montaquila and others added 3 commits November 11, 2026 14:23
Retain existing endpoint selection and path resolution behavior, document the declaration-only contract, and remove ASPIREMCP001 suppressions.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the WithMcpServer stabilization.

No open issues 🎉

Review effort: Balanced

@github-actions

This comment has been minimized.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

Copy link
Copy Markdown
Contributor

Tests selector

52 / 101 PR test projects · 4 PR jobs, from 5 changed files.

Selected PR test projects (52 / 101)

Aspire.Cli.EndToEnd.Tests, Aspire.Hosting.Analyzers.Tests, Aspire.Hosting.Azure.EntraId.Tests, Aspire.Hosting.Azure.Kubernetes.Tests, Aspire.Hosting.Azure.Kusto.Tests, Aspire.Hosting.Azure.Provisioning.Tests, Aspire.Hosting.Azure.Tests, Aspire.Hosting.Blazor.Tests, Aspire.Hosting.Browsers.Tests, Aspire.Hosting.CodeGeneration.Go.Tests, Aspire.Hosting.CodeGeneration.Java.Tests, Aspire.Hosting.CodeGeneration.Python.Tests, Aspire.Hosting.CodeGeneration.Rust.Tests, Aspire.Hosting.CodeGeneration.TypeScript.Tests, Aspire.Hosting.Containers.Tests, Aspire.Hosting.DevTunnels.Tests, Aspire.Hosting.Docker.Tests, Aspire.Hosting.Dotnet.Tests, Aspire.Hosting.DotnetTool.Tests, Aspire.Hosting.EntityFrameworkCore.Tests, Aspire.Hosting.Foundry.Tests, Aspire.Hosting.Garnet.Tests, Aspire.Hosting.Go.Tests, Aspire.Hosting.Java.Tests, Aspire.Hosting.JavaScript.Tests, Aspire.Hosting.Kafka.Tests, Aspire.Hosting.Keycloak.Tests, Aspire.Hosting.Kubernetes.Tests, Aspire.Hosting.Maui.Tests, Aspire.Hosting.Milvus.Tests, Aspire.Hosting.MongoDB.Tests, Aspire.Hosting.MySql.Tests, Aspire.Hosting.Nats.Tests, Aspire.Hosting.OpenAI.Tests, Aspire.Hosting.Oracle.Tests, Aspire.Hosting.Orleans.Tests, Aspire.Hosting.PostgreSQL.Tests, Aspire.Hosting.Python.Tests, Aspire.Hosting.Qdrant.Tests, Aspire.Hosting.RabbitMQ.Tests, Aspire.Hosting.Radius.Tests, Aspire.Hosting.Redis.Tests, Aspire.Hosting.RemoteHost.Tests, Aspire.Hosting.Rust.Tests, Aspire.Hosting.Seq.Tests, Aspire.Hosting.SqlServer.Tests, Aspire.Hosting.Testing.Tests, Aspire.Hosting.Tests, Aspire.Hosting.Valkey.Tests, Aspire.Hosting.Yarp.Tests, Aspire.Playground.Tests, Aspire.Templates.Tests

Selected PR jobs (4)

cli-starter-validation, extension-e2e, polyglot, typescript-api-compat


How these were chosen — grouped by what changed

⚠️ 39 of the 52 selected test projects come from a single change — src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs.

🔧 src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs (changed source)
→ 39 via the project graph

show 39

Aspire.Hosting.Analyzers.Tests (2 hops), Aspire.Hosting.Azure.EntraId.Tests (2 hops), Aspire.Hosting.Azure.Kubernetes.Tests (2 hops), Aspire.Hosting.Azure.Kusto.Tests (2 hops), Aspire.Hosting.Azure.Provisioning.Tests (3 hops), Aspire.Hosting.Azure.Tests, Aspire.Hosting.Browsers.Tests (2 hops), Aspire.Hosting.CodeGeneration.Java.Tests, Aspire.Hosting.CodeGeneration.Python.Tests, Aspire.Hosting.CodeGeneration.Rust.Tests, Aspire.Hosting.Containers.Tests (2 hops), Aspire.Hosting.DevTunnels.Tests (2 hops), Aspire.Hosting.DotnetTool.Tests (2 hops), Aspire.Hosting.Foundry.Tests (2 hops), Aspire.Hosting.Garnet.Tests (2 hops), Aspire.Hosting.Go.Tests (2 hops), Aspire.Hosting.Java.Tests (2 hops), Aspire.Hosting.JavaScript.Tests (2 hops), Aspire.Hosting.Kafka.Tests (2 hops), Aspire.Hosting.Keycloak.Tests (2 hops), Aspire.Hosting.Maui.Tests, Aspire.Hosting.Milvus.Tests (2 hops), Aspire.Hosting.MongoDB.Tests (2 hops), Aspire.Hosting.MySql.Tests (2 hops), Aspire.Hosting.Nats.Tests (2 hops), Aspire.Hosting.OpenAI.Tests (2 hops), Aspire.Hosting.Oracle.Tests (2 hops), Aspire.Hosting.Orleans.Tests (2 hops), Aspire.Hosting.Python.Tests (2 hops), Aspire.Hosting.Qdrant.Tests (2 hops), Aspire.Hosting.RabbitMQ.Tests (2 hops), Aspire.Hosting.Redis.Tests (2 hops), Aspire.Hosting.RemoteHost.Tests, Aspire.Hosting.Rust.Tests (2 hops), Aspire.Hosting.Seq.Tests (2 hops), Aspire.Hosting.SqlServer.Tests (2 hops), Aspire.Hosting.Valkey.Tests (2 hops), Aspire.Hosting.Yarp.Tests (2 hops), Aspire.Playground.Tests

🔧 src/Aspire.Hosting.PostgreSQL/PostgresBuilderExtensions.cs (changed source)
→ 1 directly: Aspire.Hosting.PostgreSQL.Tests
→ 5 via the project graph: Aspire.Hosting.Docker.Tests (2 hops), Aspire.Hosting.EntityFrameworkCore.Tests (2 hops), Aspire.Hosting.Kubernetes.Tests (2 hops), Aspire.Hosting.Radius.Tests, Aspire.Hosting.Testing.Tests (2 hops)

🧪 tests/Aspire.Hosting.Tests/WithMcpServerTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Tests
→ 2 via the project graph: Aspire.Hosting.Blazor.Tests, Aspire.Hosting.Dotnet.Tests

📦 affected project Aspire.Hosting.Dotnet
→ 2 tests: Aspire.Cli.EndToEnd.Tests, Aspire.Templates.Tests

📦 affected project Aspire.Hosting.PostgreSQL
→ 1 test: Aspire.Cli.EndToEnd.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.Go.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.go (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.Go.Tests

🧪 tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/TwoPassScanningGeneratedAspire.verified.ts (changed test)
→ 1 directly: Aspire.Hosting.CodeGeneration.TypeScript.Tests

Job reasons

Job Triggered by
cli-starter-validation affected project Aspire.Hosting.PostgreSQL
extension-e2e • src/Aspire.Hosting/McpServerResourceBuilderExtensions.cs
• affected project Aspire.Hosting
polyglot • affected project Aspire.Hosting.PostgreSQL
• affected project Aspire.Hosting.Azure.Provisioning.PostgreSql
typescript-api-compat affected project Aspire.Hosting.PostgreSQL

Selection computed for commit a4095d3.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Generated TypeScript and Go SDK docs incorrectly describe null as selecting the base endpoint URL and need an empty-string documentation override plus regenerated snapshots.

1 open issue

Review effort: Balanced

/// <param name="path">An optional path to append to the endpoint URL when forming the MCP server address. Defaults to <c>"/mcp"</c>.</param>
/// <param name="endpointName">An optional name of the endpoint that hosts the MCP server. If not specified, defaults to the first HTTPS or HTTP endpoint.</param>
/// <param name="path">An optional path to append to the endpoint URL when forming the MCP server address. Defaults to <c>"/mcp"</c>.
/// A leading slash is added if missing. A null or empty value uses the endpoint URL without an additional path.</param>
@maddymontaquila
Maddy Montaquila (maddymontaquila) merged commit 6a7a7c4 into release/17.0 Nov 15, 2026
346 of 348 checks passed
@microsoft-github-policy-service microsoft-github-policy-service Bot added this to the 17.0 milestone Nov 15, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Pull request created: #2171

Generated by PR Documentation Check · copilot · auto · 28.3 AIC · ⌖ 1.19 AIC · ⊞ 7.4K

@aspire-repo-bot

Copy link
Copy Markdown
Contributor

📝 Documentation has been drafted in microsoft/aspire.dev#2171 targeting release/17.0.

Documents that WithMcpServer is stable (no ASPIREMCP001 suppression needed) and its endpoint/path contract. Updated resource-mcp-servers.mdx, aspiremcp001.mdx, and diagnostics overview.mdx. Signals: diagnostic_documentation_changed (docs/list-of-diagnostics.md), pr_body_has_user_facing_section, pr_body_has_cli_flag_mention, pr_body_has_security_marker.

Note

This draft PR needs human review before merging.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-integrations Issues pertaining to Aspire Integrations packages

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants