Skip to content

Commit 04015ec

Browse files
JamesNKJamesNK
authored
Add Aspire MCP docs (#5446)
1 parent de2d81a commit 04015ec

File tree

4 files changed

+126
-0
lines changed

4 files changed

+126
-0
lines changed

‎docs/fundamentals/dashboard/mcp-server.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: Aspire MCP server
3+
description: Learn how to use Aspire MCP server to develop your apps.
4+
ms.date: 11/03/2025
5+
ms.topic: reference
6+
---
7+
8+
# Aspire MCP server
9+
10+
The Aspire MCP server is a local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server. Aspire MCP integrates Aspire into your development AI eco-system.
11+
12+
With Aspire MCP, you can:
13+
14+
- Query resources, including resource states, endpoints, health status and commands.
15+
- Debug with real-time console logs.
16+
- Investigate development time telemetry, such as structured logs and distributed tracing across resources.
17+
- Execute resource commands.
18+
19+
## Get started
20+
21+
To get started, configure your local AI assistant to use Aspire MCP.
22+
23+
1. Run your Aspire app.
24+
2. Open the Aspire dashboard and click on the MCP button in the top right corner of the dashboard. This launches a dialog that contains instructions for using Aspire MCP.
25+
3. Use the specified details in the dialog to configure your local AI assistant.
26+
27+
Important settings required to use Aspire MCP:
28+
29+
- `url` - Aspire MCP address.
30+
- `type` - `http` to indicate Aspire MCP is a [streamable-HTTP MCP server](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
31+
- `x-mcp-api-key` - An HTTP header with a key to secure access to the MCP server.
32+
33+
:::image type="content" source="media/mcp-server/mcp-dialog.png" lightbox="media/mcp-server/mcp-dialog.png" alt-text="A screenshot of the Aspire MCP dialog in the dashboard with the url and API header highlighted.":::
34+
35+
There isn't a standard way to configure AI assistants with new MCP servers. Configuration varies depending on your local AI assistant:
36+
37+
- [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
38+
- [Codex](https://developers.openai.com/codex/mcp/)
39+
- [Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli#add-an-mcp-server)
40+
- [Cursor](https://cursor.com/docs/context/mcp#installing-mcp-servers)
41+
- [VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
42+
- [Visual Studio](/visualstudio/ide/mcp-servers#options-for-adding-an-mcp-server)
43+
44+
## Your first prompts
45+
46+
After configuration, try asking your AI assistant:
47+
48+
> Are all my resources running?
49+
50+
> Analyze HTTP requests performance for RESOURCE_NAME.
51+
52+
> Restart unhealthy resources.
53+
54+
## Tools
55+
56+
The Aspire MCP server provides the following tools:
57+
58+
- `list_resources` - Lists all resources, including their state, health status, source, endpoints, and commands.
59+
- `list_console_logs` - Lists console logs for a resource.
60+
- `list_structured_logs` - Lists structured logs, optionally filtered by resource name.
61+
- `list_traces` - Lists distributed traces. Traces can be filtered using an optional resource name parameter.
62+
- `list_trace_structured_logs` - Lists structured logs for a trace.
63+
- `execute_resource_command` - Executes a resource command. This tool accepts parameters for the resource name and command name.
64+
65+
By default all resources, console logs and telemetry is accessible by Aspire MCP. Resources and associated telemetry can be excluded from MCP results by annotating the resource in the app host with `ExcludeFromMcp()`.
66+
67+
```csharp
68+
var builder = DistributedApplication.CreateBuilder(args);
69+
70+
var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
71+
.ExcludeFromMcp();
72+
73+
builder.AddProject<Projects.AspireApp_Web>("webfrontend")
74+
.WithExternalHttpEndpoints()
75+
.WithReference(apiService);
76+
77+
builder.Build().Run();
78+
```
79+
80+
## Troubleshooting
81+
82+
### MCP connection secured with self-signed HTTPS certificate not supported by some AI assistants
83+
84+
An MCP connection secured with HTTPS is recommended for security. However, some AI assistants currently don't support calling endpoints secured with a trusted, self-signed certificate. This includes the Aspire MCP, which is secured using [a self-signed certificate](https://learn.microsoft.com/dotnet/core/additional-tools/self-signed-certificates-guide).
85+
86+
Currently the only work around for using Aspire MCP with these AI assistants is to configure an `http` MCP endpoint.
87+
88+
- If you already launch your Aspire app with [the `http` launch profile](https://learn.microsoft.com/dotnet/aspire/fundamentals/launch-profiles) then your app isn't using HTTPS and you don't need to do anything.
89+
- If you use HTTPS everywhere, you can configure just the MCP endpoint to use `http` by updating *launchSettings.json*.
90+
- Set `ASPIRE_DASHBOARD_MCP_ENDPOINT_URL` to an `http` address.
91+
- Add `ASPIRE_ALLOW_UNSECURED_TRANSPORT` set to `true`.
92+
93+
:::code language="json" source="snippets/Mcp/launchSettings.json" highlight="14,15":::
94+
95+
> [!WARNING]
96+
> This configuration will remove transport security from Aspire MCP communication. It could allow data to be read by a third party.
97+
98+
## Limitations
99+
100+
### Data size
101+
102+
AI models have limits on how much data they can process at once. Aspire MCP may limit the amount of data returned from tools when necessary.
103+
104+
- Large data fields (e.g., long exception stack traces) may be truncated.
105+
- Requests involving large collections of telemetry may be shortened by omitting older items.

‎docs/fundamentals/dashboard/media/mcp-server/mcp-dialog.png‎

182 KB
Loading

‎docs/fundamentals/dashboard/snippets/Mcp/launchSettings.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"profiles": {
3+
"https": {
4+
"commandName": "Project",
5+
"launchBrowser": true,
6+
"dotnetRunMessages": true,
7+
"applicationUrl": "https://localhost:15887;http://localhost:15888",
8+
"environmentVariables": {
9+
"ASPNETCORE_ENVIRONMENT": "Development",
10+
"DOTNET_ENVIRONMENT": "Development",
11+
"ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:16037",
12+
"ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "https://localhost:16038",
13+
"ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:17037",
14+
"ASPIRE_DASHBOARD_MCP_ENDPOINT_URL": "http://localhost:16036",
15+
"ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"
16+
}
17+
}
18+
}
19+
}

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,8 @@ items:
100100
href: fundamentals/dashboard/explore.md
101101
- name: GitHub Copilot
102102
href: fundamentals/dashboard/copilot.md
103+
- name: Aspire MCP
104+
href: fundamentals/dashboard/mcp-server.md
103105
- name: Standalone mode
104106
items:
105107
- name: Overview

0 commit comments

Comments
 (0)