Aspire MCP Templates

This repository provides templates and reusable components for integrating Model Context Protocol (MCP) servers with .NET Aspire and the MCP Inspector.

Overview

The repository is organized into two main sections:

Reusable Components

These libraries can be used in any .NET project to add MCP and Aspire integration:

• Mcp.NamedPipeTransport - Named pipe server transport implementation for MCP servers
• Mcp.NamedPipeProxy - Stdio-to-named-pipe bridge for connecting MCP Inspector to stdio-based MCP servers
• Mcp.Aspire.McpInspector - Aspire AppHost extensions for adding MCP Inspector integration
• Mcp.AspireIntegration - MCP server extensions for transparent Aspire support

Template

AspireWithMcp/ - Complete working example of an MCP server integrated with .NET Aspire:

• AspireWithMcp.McpServer - MCP server with Aspire Inspector support
• AspireWithMcp.AppHost - Aspire orchestration with MCP server and Inspector
• AspireWithMcp.ServiceDefaults - Standard Aspire service defaults

Getting Started

Prerequisites

• .NET 9.0 SDK
• MCP Inspector installed globally: npm install -g @modelcontextprotocol/inspector

Running the Template

1. Clone this repository:

   git clone https://github.com/JakeRadMSFT/Aspire-MCP-Templates.git
   cd Aspire-MCP-Templates

2. Build the solution:

   dotnet build AspireWithMcp/AspireWithMcp.sln

3. Run the Aspire AppHost:

   dotnet run --project AspireWithMcp/AspireWithMcp.AppHost

4. Open the Aspire dashboard (URL shown in console output)

5. The MCP Inspector will automatically start and connect to the MCP server

How It Works

MCP Server Integration

The MCP server uses a simple extension to enable Aspire integration:

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithTools<RandomNumberTools>()
    .WithAspireMcpInspectorSupport();  // Enables Aspire integration

The .WithAspireMcpInspectorSupport() extension:

• Detects when running in Aspire (via --pipe-name argument)
• Transparently replaces stdio transport with named pipe transport
• Allows the MCP server code to remain unchanged

AppHost Configuration

The Aspire AppHost wires up the MCP server and Inspector:

// Add MCP server with named pipe argument
var mcpServer = builder.AddProject<Projects.AspireWithMcp_McpServer>("mcp-server")
    .WithArgs(["--pipe-name=aspire-mcp-server"]);

// Add MCP Inspector that connects via proxy
var proxyPath = Path.GetFullPath("../../Mcp.NamedPipeProxy/bin/Debug/net9.0/Mcp.NamedPipeProxy.exe");
builder.AddMcpInspector("mcp-inspector", mcpServer, proxyPath, "aspire-mcp-server");

Architecture

   MCP Inspector     
   (Web UI)          

            stdio

  NamedPipeProxy     
  (stdio  pipes)    

            named pipes

   MCP Server        
  (NamedPipe         
   Transport)        

1. MCP Server runs with named pipe transport when launched by Aspire
2. NamedPipeProxy bridges stdio (used by Inspector) to named pipes
3. MCP Inspector connects to the proxy via stdio and provides a web UI

Using the Reusable Components

In Your MCP Server

1. Add package references:

   dotnet add package ModelContextProtocol
   dotnet add reference path/to/Mcp.AspireIntegration/Mcp.AspireIntegration.csproj

2. Add the extension to your MCP server:

   builder.Services
       .AddMcpServer()
       .WithStdioServerTransport()
       .WithTools<YourTools>()
       .WithAspireMcpInspectorSupport();

In Your Aspire AppHost

1. Add project references:

   dotnet add reference path/to/Mcp.Aspire.McpInspector/Mcp.Aspire.McpInspector.csproj

2. Configure the AppHost:

   using Mcp.Aspire.McpInspector;
   
   var mcpServer = builder.AddProject<Projects.YourMcpServer>("mcp-server")
       .WithArgs(["--pipe-name=your-pipe-name"]);
   
   var proxyPath = "path/to/Mcp.NamedPipeProxy.exe";
   builder.AddMcpInspector("mcp-inspector", mcpServer, proxyPath, "your-pipe-name");

Components Details

Mcp.NamedPipeTransport

Provides WithNamedPipeServerTransport() extension for MCP servers to use named pipes instead of stdio. Uses a two-pipe architecture (separate input/output pipes) for bidirectional communication.

Mcp.NamedPipeProxy

Console application that connects an MCP server's stdio to named pipes. Accepts --pipe-name=<name> argument and creates two pipes: <name> (input) and <name>-out (output).

Mcp.Aspire.McpInspector

Aspire extension that adds MCP Inspector to your distributed application. The AddMcpInspector() method:

• Launches the MCP Inspector (requires global npm install)
• Connects it to your MCP server via the NamedPipeProxy
• Manages dependencies to ensure proper startup order

Mcp.AspireIntegration

Provides WithAspireMcpInspectorSupport() extension for MCP servers. When --pipe-name is detected:

• Removes the stdio transport from DI
• Adds named pipe transport instead
• Logs the transport override

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.