Codebelt.Extensions.Swashbuckle.AspNetCore.ModelContextProtocol

Overview

Codebelt.Extensions.Swashbuckle.AspNetCore.ModelContextProtocol adds Model Context Protocol documentation to Swashbuckle-generated OpenAPI documents in ASP.NET Core applications. It extends Codebelt.Extensions.Swashbuckle.AspNetCore with an MCP-specific document filter that injects the streamable HTTP endpoint, optional legacy SSE transport endpoints, and JSON-RPC 2.0 request and response shapes.

When tool example generation is enabled, the filter also reflects over discovered MCP server tools and adds named request body examples for tools/call payloads.

Key APIs

SwaggerGenOptionsExtensions.AddMcpServer is the main consumer entry point. It extends SwaggerGenOptions and registers a configured McpDocumentFilter so MCP operations appear in the generated OpenAPI document.

McpDocumentOptions.Pattern controls the documented route prefix and defaults to /mcp. Functional tests show that overriding it changes the generated MCP paths, including the optional legacy transport routes.

McpDocumentOptions.EnableLegacySse controls whether the legacy GET {Pattern}/sse and POST {Pattern}/message endpoints are added to the document. It defaults to false, so only the streamable HTTP endpoint is documented unless you opt in.

McpDocumentOptions.IncludeTools controls whether discovered [McpServerTool] methods are surfaced as named request examples on the application/json request body. It defaults to true, and discovery excludes CancellationToken plus ModelContextProtocol infrastructure parameters.

McpDocumentFilter is the underlying DocumentFilter<McpDocumentOptions> implementation. Its Apply override adds the MCP tag, the POST {Pattern} operation with JSON-RPC 2.0 request and response schemas, and the optional legacy transport operations when enabled.

Basic usage

using Codebelt.Extensions.Swashbuckle.AspNetCore.ModelContextProtocol;
using Codebelt.Extensions.Xunit;
using Swashbuckle.AspNetCore.SwaggerGen;
using Xunit;

namespace MyProject.Tests;

public class McpSwaggerRegistrationTest : Test
{
    public McpSwaggerRegistrationTest(ITestOutputHelper output) : base(output)
    {
    }

    [Fact]
    public void ShouldCaptureCustomMcpRoute_WhenRegisteringDocumentFilter()
    {
        var swagger = new SwaggerGenOptions();

        swagger.AddMcpServer(options =>
        {
            options.Pattern = "/ai/mcp";
            options.EnableLegacySse = true;
        });

        var descriptor = Assert.Single(swagger.DocumentFilterDescriptors);
        var filter = Assert.IsType<McpDocumentFilter>(descriptor.FilterInstance);

        TestOutput.WriteLine($"Pattern: {filter.Options.Pattern}");
        TestOutput.WriteLine($"Legacy SSE: {filter.Options.EnableLegacySse}");

        Assert.Equal("/ai/mcp", filter.Options.Pattern);
        Assert.True(filter.Options.EnableLegacySse);
    }
}

Use this pattern when you want AddMcpServer to own the MCP route metadata that later flows into generated OpenAPI documents. It matters because the extension registers a concrete McpDocumentFilter with the configured path and transport options instead of leaving those settings scattered across raw Swashbuckle callbacks.

Installation

dotnet add package Codebelt.Extensions.Swashbuckle.AspNetCore.ModelContextProtocol

Usage guidance

Adopt this package when you already use Swashbuckle in ASP.NET Core and need your generated OpenAPI document to describe MCP streamable HTTP transport, optional legacy SSE transport, and JSON-RPC request and response envelopes. If you do not expose MCP routes, or if you only need general Swagger document customization, plain Swashbuckle configuration or the base Codebelt.Extensions.Swashbuckle.AspNetCore package is the better fit.