Configure the MCP server

Este conteúdo não está disponível em sua língua ainda.

Aspire provides powerful integrations with AI assistants through the Model Context Protocol (MCP). This enables agentic development — a workflow where AI assistants can directly interact with your Aspire application to help you build, debug, and monitor your distributed applications.

Get started with `aspire mcp init`

The easiest way to configure the Aspire MCP server is using the Aspire CLI. The aspire mcp init command automatically detects your AI development environment and creates the necessary configuration files.

Open a terminal in your Aspire project directory (the folder containing your AppHost).
Run the following command:
Aspire CLI
```
aspire mcp init
```
The command detects supported agent environments (such as VS Code with GitHub Copilot, or other MCP-compatible tools) and creates the appropriate configuration files.

That’s it! The Aspire CLI handles all the configuration details for you, including setting up the MCP server connection and any required authentication.

Understanding the configuration

When you run aspire mcp init, the CLI creates configuration files appropriate for your detected environment. Here are examples of the configuration files created for different AI assistants:

Creates or updates .vscode/mcp.json:

{
  "servers": {
    "aspire": {
      "type": "stdio",
      "command": "aspire",
      "args": [
        "mcp",
        "start"
      ]
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]
    }
  }
}

Creates or updates ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "aspire": {
      "type": "local",
      "command": "aspire",
      "args": [
        "mcp",
        "start"
      ]
    },
    "playwright": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ],
      "tools": [
        "*"
      ]
    }
  }
}

Creates or updates .mcp.json:

{
  "mcpServers": {
    "aspire": {
      "command": "aspire",
      "args": [
        "mcp",
        "start"
      ]
    },
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]
    }
  }
}

Creates or updates opencode.jsonc:

{
  "mcp": {
    "aspire": {
      "type": "local",
      "command": [
        "aspire",
        "mcp",
        "start"
      ],
      "enabled": true
    },
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@playwright/mcp@latest"
      ],
      "enabled": true
    }
  }
}

Your first prompts

Once you’ve configured the MCP server, start your preferred agentic coding environment. The Aspire MCP server will automatically start and connect, giving your AI assistant access to your running Aspire application.

Try asking your AI assistant:

“Are all my resources running?”

“Analyze HTTP requests performance for RESOURCE_NAME.”

“Restart unhealthy resources.”

Tools

The Aspire MCP server provides the following tools:

list_resources - Lists all resources, including their 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 trace.
execute_resource_command - Executes a resource command. This tool accepts parameters for the resource name and command name.
list_apphosts - Lists all AppHost connections currently detected by the Aspire MCP server, showing which AppHosts are within the working directory scope and which are outside.
select_apphost - Selects which AppHost to use when multiple AppHosts are running. The path can be a fully qualified path or a workspace root relative path.
list_integrations - Lists available Aspire hosting integrations. These are NuGet packages that can be added to an Aspire AppHost project to integrate with various services like databases, message brokers, and cloud services.
get_integration_docs - Gets documentation for a specific Aspire hosting integration package. Use this tool to get detailed information about how to use an integration within the AppHost.

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().

var builder = DistributedApplication.CreateBuilder(args);

var apiservice = builder.AddProject<Projects.AspireApp_ApiService>("apiservice")
    .ExcludeFromMcp();

builder.AddProject<Projects.AspireApp_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(apiService);

builder.Build().Run();

Supported AI assistants

The aspire mcp init command supports the following AI assistants:

Troubleshooting

Aspire MCP is designed to work seamlessly with AI assistants, but you may encounter some setup challenges depending on your environment. If you run into issues, check the open MCP issues on GitHub for known problems and solutions.

Limitations

Aspire MCP is a powerful tool, but there are a few things to keep in mind when using it.

Data size

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.

Large data fields (e.g., long exception stack traces) may be truncated.
Requests involving large collections of telemetry may be shortened by omitting older items.