MCP Server Feature

Summary

Blazing Story provides an MCP server feature that allows Blazing Story to expose information about its components, stories, and documentation pages to AI agents, enabling highly accurate code generation and documentation lookup.

To catch up on the power of the Blazing Story's MCP server feature, you can watch the following introduction video.

Currently, the MCP server feature is available only in the Blazing Story app running on Blazor Server. It is not available in the Blazing Story app running on Blazor WebAssembly.

Available Tools

Once an AI agent is connected to the Blazing Story MCP server, the following tools become available to it. They fall into two groups: tools for exploring components and their stories, and tools for accessing custom documentation pages.

Component and Story Tools

These tools let an AI agent discover exactly which components your catalog offers and how to use them correctly — so it can generate code that matches your real component APIs instead of guessing.

Custom Documentation Page Tools

These tools expose your hand-written custom pages and Markdown pages — getting-started guides, setup instructions, design notes, and the like — so the agent can consult your project's own documentation instead of relying on general knowledge.

Create A New Blazing Story App With The MCP Server Feature

When you create a new Blazing Story app project, you can enable the MCP server feature by checking the "Enable the MCP server feature" checkbox in the project creation dialog.

Or, if you are working on dotnet CLI, you can do that by running the dotnet new blazingstoryserver command with the -mcp option, like below:

dotnet new blazingstoryserver -mcp

Migrate Your Blazing Story App To Enable The MCP Server Feature

To enable the MCP server feature in your existing Blazing Story app, you need to follow these steps:

1. Upgrade your Blazing Story app project to reference the latest version of the Blazing Story NuGet package.

2. Add the BlazingStory.McpServer package reference to your Blazing Story app project.

   If you are working on Visual Studio, you can do that by right-clicking the project in the solution explorer and selecting "Manage NuGet Packages...", then searching for the BlazingStory.McpServer package and installing it.

   If you are working on dotnet CLI, you can do that with the following command:

   dotnet add package BlazingStory.McpServer
   

3. Add the AddBlazingStoryMcpServer method call to the Program.cs file of your Blazing Story app project to register the MCP server services in the dependency injection container.

   📄 Program.cs

   ...
   // 👇 Add the necessary using directive for the MCP server.
   using BlazingStory.McpServer;
   ...
   var builder = WebApplication.CreateBuilder(args);
   ...
   // 👇 Add services to the container.
   builder.Services.AddBlazingStoryMcpServer();
   ...
   

4. Add the MapBlazingStoryMcp method call to the app object in the Program.cs file to register the Blazing Story MCP server middleware.

   📄 Program.cs

   ...
   app.UseHttpsRedirection();
   
   // 👇 Register the Blazing Story MCP server middleware.
   app.MapBlazingStoryMcp();
   app.MapStaticAssets();
   app.UseRouting();
   app.UseAntiforgery();
   ...
   

Usage

The transport type of the MCP server feature of the Blazing Story is Streamable HTTP. It doesn't support STDIO transport type for now.

Once you have enabled the MCP server feature in your Blazing Story app, you can access the MCP server at the /mcp/blazingstory endpoint of your Blazing Story app.

HTTP Transport Settings

Stateless By Default

The HTTP transport of the MCP server is stateless by default. The server answers each request on its own and keeps no session between requests. Every tool of the MCP server only reads your catalog, so it doesn't need a session. MCP clients that follow older revisions of the MCP specification also work without a session ID.

Configure The HTTP Transport

The AddBlazingStoryMcpServer method returns an IMcpServerBuilder object. To change the settings of the HTTP transport, call the WithHttpTransport method on it in the Program.cs file.

For example, if your MCP client needs a session, you can turn on the hybrid session mode like below. In this mode, the server issues a session ID to clients that follow older revisions of the MCP specification, and stays stateless for the other clients.

...
// 👇 Add the necessary using directive for the HTTP transport options.
using ModelContextProtocol.AspNetCore;
...
builder.Services.AddBlazingStoryMcpServer()
    // 👇 Configure the HTTP transport of the MCP server.
    .WithHttpTransport(options =>
    {
        options.SessionMode = HttpServerSessionMode.StatefulForInitializeClients;
    });
...

Enable The Legacy SSE Transport

The legacy SSE transport (the /mcp/blazingstory/sse endpoint) is disabled by default. If you still need it, set the EnableLegacySse option to true together with a stateful session mode. The legacy SSE transport needs a session, so enabling it in the stateless mode throws an exception when the app starts.

...
builder.Services.AddBlazingStoryMcpServer()
    .WithHttpTransport(options =>
    {
        // 👇 The legacy SSE transport needs a stateful session mode.
        options.SessionMode = HttpServerSessionMode.StatefulForInitializeClients;
#pragma warning disable MCP9004
        options.EnableLegacySse = true;
#pragma warning restore MCP9004
    });
...