Setting the file. One moment.
Subchapter 33.6
references/mcp-server.mdMarkdown8 KBView on GitHub
Aspire exposes an MCP (Model Context Protocol) server that lets AI coding assistants query and control your running distributed application, and search Aspire documentation. This enables AI tools to inspect resource status, read logs, view traces, restart services, and look up docs — all from within the AI assistant’s context.
The easiest way to configure the MCP server is using the Aspire CLI:
# Open a terminal in your project directory
aspire mcp initThe command walks you through an interactive setup:
.vscode/mcp.json)AGENTS.md with Aspire-specific instructions for AI agentsNote:
aspire mcp inituses interactive prompts (Spectre.Console). It must be run in a real terminal — the VS Code integrated terminal may not handle the prompts correctly. Use an external terminal if needed.
When you run aspire mcp init, the CLI creates configuration files appropriate for your detected environment.
Creates or updates .vscode/mcp.json:
{
"servers": {
"aspire": {
"type": "stdio",
"command": "aspire",
"args": ["mcp", "start"]
}
}
}The tools available depend on your Aspire CLI version. Check with aspire --version.
These tools require a running AppHost (aspire run).
| Tool | Description |
|---|---|
list_resources | Lists all resources, including state, health status, source, endpoints, and commands |
list_console_logs | Lists console logs for a resource |
list_structured_logs | Lists structured logs, optionally filtered by resource name |
list_traces | Lists distributed traces. Traces can be filtered using an optional resource name parameter |
list_trace_structured_logs | Lists structured logs for a specific trace |
execute_resource_command | Executes a resource command (accepts resource name and command name) |
| Tool | Description |
|---|---|
list_apphosts | Lists all detected AppHost connections, showing which are in/out of working directory scope |
select_apphost | Selects which AppHost to use when multiple are running |
These work without a running AppHost.
| Tool | Description |
|---|---|
list_integrations | Lists available Aspire hosting integrations (NuGet packages for databases, message brokers, cloud services, etc.) |
get_integration_docs | Gets documentation for a specific Aspire hosting integration package |
Version gate: These tools were added in PR #14028 (opens in a new tab) and ship in Aspire CLI 13.2. If you are on 13.1, these tools will NOT appear. To get them early, update to the daily channel:
aspire update --self --channel daily.
| Tool | Description |
|---|---|
list_docs | Lists all available documentation from aspire.dev |
search_docs | Performs weighted lexical search across indexed aspire.dev documentation |
get_doc | Retrieves a specific document by its slug |
These tools index aspire.dev content using the llms.txt specification and provide weighted lexical search (titles 10x, summaries 8x, headings 6x, code 5x, body 1x). They work without a running AppHost.
If you are on Aspire CLI 13.1 and don’t have list_docs/search_docs/get_doc, use Context7 as a fallback for documentation queries. See the SKILL.md documentation research section for details.
Resources and associated telemetry can be excluded from MCP results by annotating the resource:
var builder = DistributedApplication.CreateBuilder(args);
var apiService = builder.AddProject<Projects.Api>("apiservice")
.ExcludeFromMcp(); // Hidden from MCP tools
builder.AddProject<Projects.Web>("webfrontend")
.WithExternalHttpEndpoints()
.WithReference(apiService);
builder.Build().Run();The aspire mcp init command supports:
The MCP server uses the STDIO transport protocol and may work with other agentic coding environments that support this protocol.
Once MCP is configured, your AI assistant can:
Inspect running state:
Read logs:
View traces:
Control resources:
Search docs (13.2+):
list_integrations/get_integration_docs for integration-specific docs.)If you run into issues, check the open MCP issues on GitHub (opens in a new tab).