Content
# 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](https://github.com/modelcontextprotocol/inspector) installed globally: `npm install -g @modelcontextprotocol/inspector`
### Running the Template
1. Clone this repository:
```bash
git clone https://github.com/JakeRadMSFT/Aspire-MCP-Templates.git
cd Aspire-MCP-Templates
```
2. Build the solution:
```bash
dotnet build AspireWithMcp/AspireWithMcp.sln
```
3. Run the Aspire AppHost:
```bash
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:
```csharp
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:
```csharp
// 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:
```bash
dotnet add package ModelContextProtocol
dotnet add reference path/to/Mcp.AspireIntegration/Mcp.AspireIntegration.csproj
```
2. Add the extension to your MCP server:
```csharp
builder.Services
.AddMcpServer()
.WithStdioServerTransport()
.WithTools<YourTools>()
.WithAspireMcpInspectorSupport();
```
### In Your Aspire AppHost
1. Add project references:
```bash
dotnet add reference path/to/Mcp.Aspire.McpInspector/Mcp.Aspire.McpInspector.csproj
```
2. Configure the AppHost:
```csharp
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.
