fix: root path(/) is forcibly occupied

[JeffreySu]

Motivation and Context

1. reference https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http, use /mcp as the default endpoint(make way of the root path)
2. retain the customization ability of the root path(homepage)

We have to make sure that the homepage is not forcibly occupied during the integration, keep custom(or default from .NET Core setting) homepage, /sse and /message urls under root url together.

How Has This Been Tested?

Set occupyRootUrl to false, then you can see default home page again for project.

Breaking Changes

No. Default value for occupyRootUrl is true, the same to initial condition.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[halter73]

The occupyRootUrl doesn't seem very ergonomic to me.

Why not call app.MapMcp("/mcp") similar to this test if you want to use /mcp as your route?

Is it that you don't want to route /mcp/sse and /mcp/message to the legacy "HTTP with SSE" transport? I've considered adding an HttpServerTransportOptions to disable those endpoints, but I didn't see much point in disabling them.

[JeffreySu]

The occupyRootUrl doesn't seem very ergonomic to me.

Why not call app.MapMcp("/mcp") similar to this test if you want to use /mcp as your route?

Is it that you don't want to route /mcp/sse and /mcp/message to the legacy "HTTP with SSE" transport? I've considered adding an HttpServerTransportOptions to disable those endpoints, but I didn't see much point in disabling them.

Yes, if you use app.MapMcp("/mcp"), you have to use /mcp/sse and /mcp/message. It is more reasonable to be able to directly use /sse and /message when docking Servers to Client.

[halter73]

It is more reasonable to be able to directly use /sse and /message when docking Servers to Client.

You can already get that behavior by calling app.MapMcp("/") or just app.MapMcp().

Is it that you want to be able to use / and /message as the endpoints? Now that we support the newer "Streamable HTTP" transport on the / endpoint that no longer needs a separate message endpoint for POST requests, can you use that instead?

[JeffreySu]

It is more reasonable to be able to directly use /sse and /message when docking Servers to Client.

You can already get that behavior by calling app.MapMcp("/") or just app.MapMcp().

Is it that you want to be able to use / and /message as the endpoints? Now that we support the newer "Streamable HTTP" transport on the / endpoint that no longer needs a separate message endpoint for POST requests, can you use that instead?

No, I want / route to my own page(like Index.cshtml), and use /mcp to support streamable endpoint, and use /message and /sse for other default endpoint(stdio & sse). In the current mode I just can use /mcp, /mcp/sse and /mcp/message to keep my own homepage working. I think this is a basic library, the situation of integration into the existing system needs to be considered (and keep default URLs - /mcp,/sse,/message at the same time).

[halter73]

I think we can look into new options we can add to give more control over the SSE route or disabling either SSE or Streamable HTTP, but I don't think we'll be adding occupyRootUrl. Please feel free to file an issue if you want to start a discussion about what these new options will look like.

Fortunately, as far as wanting to route / to your own page like Index.cshtml goes, I think you can achieve that pretty easily already with the .WithOrder() extension method.

app.MapMcp("/mcp");
app.MapMcp("/").WithOrder(1); // The higher the order, the lower the priority.
app.MapGet("/", () => "Hello World!"); // Preferred with default order 0. This could be app.MapRazorPages(); instead.

https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.routing.routeendpoint.order?view=aspnetcore-9.0#remarks