Skip to content

Augment conceptual docs with Docker-based MCP server deployment guidance#1423

Merged
jeffhandley merged 5 commits into
modelcontextprotocol:mainfrom
john-mckillip:feature/docker-based-server-examples
Jul 20, 2026
Merged

Augment conceptual docs with Docker-based MCP server deployment guidance#1423
jeffhandley merged 5 commits into
modelcontextprotocol:mainfrom
john-mckillip:feature/docker-based-server-examples

Conversation

@john-mckillip

@john-mckillip john-mckillip commented Mar 11, 2026

Copy link
Copy Markdown
Contributor

Resolves #147

PR Summary

Augments the conceptual docs with Docker-based MCP server guidance for ASP.NET Core + Streamable HTTP.

What’s Included

  1. Added a new conceptual guide for Docker deployment:
    docker.md

  2. Added a Deployment section with Docker in conceptual navigation:
    toc.yml

  3. Added Docker deployment to the conceptual docs landing page:
    index.md

  4. Added a cross-link from transport guidance to Docker deployment:
    transports.md

  5. Added Docker deployment as a next step in getting started docs:
    getting-started.md

Docker Guide Coverage

  1. Minimal ASP.NET Core MCP server baseline (WithHttpTransport + MapMcp)
  2. Multi-stage Dockerfile example
  3. Build and run commands
  4. Port mapping and endpoint guidance (/mcp and legacy /mcp/sse)
  5. Environment variable and secret-handling guidance
  6. Health/readiness notes
  7. Reverse-proxy/forwarded-header considerations

Scope

  1. Docs-only change (conceptual documentation and cross-linking)
  2. No new runnable sample project
  3. No docker-compose, registry publishing, or cloud deployment playbook additions

Validation

  1. dotnet build passed
  2. dotnet test passed after installing Node conformance dependencies via npm ci

Document how to run ASP.NET Core MCP servers in Docker using
Streamable HTTP, including a baseline server example, multi-stage
Dockerfile, build/run commands, environment variable configuration,
and deployment notes for health checks and reverse proxies.

Improve discoverability by adding Docker deployment to conceptual
navigation and linking it from transports and getting started docs.

Fixes modelcontextprotocol#147
john-mckillip and others added 4 commits March 24, 2026 10:20
…server-examples

# Conflicts:
#	docs/concepts/index.md
#	docs/concepts/toc.yml
#	docs/concepts/transports/transports.md
- Replace the endpoints list: the baseline MapMcp("/mcp") maps only the
  Streamable HTTP endpoint. Legacy SSE (/mcp/sse and /mcp/message) is not
  mapped by default and the EnableLegacySse option to enable it is obsolete,
  in both v1.4.1 and v2.0.0-preview.3. Point readers to the Transports doc.
- Remove the blank line between <!-- mlc-disable-next-line --> and the [!TIP]
  and [!IMPORTANT] callouts so the directive applies to the callout line and
  suppresses the "reference not found" warnings for [!TIP]/[!IMPORTANT].

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

Copy link
Copy Markdown
Contributor

Thanks @john-mckillip for this contribution and the thorough samples -- a really helpful addition to the deployment docs!

I've merged the latest main to clear the conflicts and pushed a change that reflects the deprecation of the legacy SSE endpoints. With the baseline MapMcp("/mcp"), only the Streamable HTTP endpoint is mapped; legacy SSE (/mcp/sse and /mcp/message) is disabled by default and EnableLegacySse is now obsolete, so the endpoints section now points readers to the Transports guide rather than listing /mcp/sse as available.

I verified the documented server against both ModelContextProtocol.AspNetCore 1.4.1 and 2.0.0-preview.3 -- it builds and serves /mcp on both, and /mcp/sse returns 404 by default on both.

@jeffhandley jeffhandley 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.

Approving -- verified the documented server builds and serves /mcp against both ModelContextProtocol.AspNetCore 1.4.1 and 2.0.0-preview.3, the DocFX build is clean, and the legacy SSE deprecation is now reflected. Thanks again @john-mckillip!

@jeffhandley
jeffhandley merged commit 71d7eea into modelcontextprotocol:main Jul 20, 2026
17 of 18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add client sample w/ guidance on wiring up dependency injection

2 participants