Configure the MCP server

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 agent init

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

1. Open a terminal in your Aspire project directory (the folder containing your AppHost).

2. Run the following command:

   Aspire CLI

   aspire agent init

3. 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.

Tip

If you don’t already have an AGENTS.md file in your project, one will be created for you. This file contains instructions that help your AI coding agent perform better when working with an Aspire-enabled codebase.

Understanding the configuration

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

VS Code

Creates or updates .vscode/mcp.json:

.vscode/mcp.json

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

Copilot CLI

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

~/.copilot/mcp-config.json

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

Claude Code

Creates or updates .mcp.json:

.mcp.json

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

Note

On Windows, commands like npx require a cmd.exe /c prefix to work correctly. This affects cross-platform portability of MCP configurations. See GitHub issue #14000 for more details.

OpenCode

Creates or updates opencode.jsonc:

opencode.jsonc

{
  "mcp": {
    "aspire": {
      "type": "local",
      "command": [
        "aspire",
        "agent",
        "mcp"
      ],
      "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.”

VS Code

Pause video

Claude Code

Copilot CLI

OpenCode

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

C# — AppHost.cs

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 agent init command supports the following AI assistants:

• VS Code
• Copilot CLI
• Claude Code
• OpenCode

Note

The Aspire MCP server uses the STDIO transport protocol and may work with other agentic coding environments that support this MCP communication protocol.

Security

The Aspire MCP server is a development-time tool designed for local use. Understanding its security model helps teams evaluate it for enterprise environments.

Security model overview

The Aspire MCP server uses the STDIO transport protocol when started via aspire agent mcp. In this mode:

• The MCP server runs as a local child process spawned by your AI assistant.
• Communication happens over standard input/output (STDIO) pipes between the AI assistant and the MCP server process.
• There are no open network ports — the MCP server doesn’t listen on any network interface.
• Only the parent process (your AI assistant) can communicate with the MCP server.

Tip

Because the STDIO transport uses pipes rather than network sockets, there is no network attack surface when using aspire agent mcp. The MCP server is only accessible to the AI assistant process that started it.

What data is accessible

The MCP server provides AI assistants with access to the following data from your running AppHost:

• Resource metadata — resource names, types, states, health status, endpoints, and available commands.
• Console logs — standard output and error streams from resources.
• Structured logs — structured log entries from resources via OpenTelemetry.
• Distributed traces — trace data showing request flow across resources.
• Integration catalog — the list of available Aspire hosting integration packages and their documentation.

The MCP server does not expose:

• Source code or file system contents.
• Environment variable values or secrets stored in configuration.
• Network traffic or raw request/response payloads.
• Access to the host machine beyond the Aspire AppHost process.

You can further restrict what the MCP server exposes by using ExcludeFromMcp() on specific resources, as described in the Tools section.

Authentication

When using the STDIO transport (the default with aspire agent mcp), no additional authentication is required because communication is restricted to the local process pipe.

For the HTTP-based MCP endpoint exposed by the Aspire dashboard (used in manual MCP configuration for older Aspire versions), an API key (x-mcp-api-key header) is required to authenticate requests. This key is generated automatically when the AppHost starts.

Enterprise deployment considerations

For teams evaluating the Aspire MCP server for organizational use:

• Development-time only — the MCP server is a development tool and is not included in published or deployed applications. It runs only during local development with aspire run.
• No external network access — using STDIO transport, the server has no network listeners and cannot be reached from other machines.
• Data stays local — telemetry and resource data remain on the developer’s machine. The MCP server doesn’t transmit data to external services. Data shared with AI assistants is governed by the AI assistant’s own data policies.
• Granular access control — use ExcludeFromMcp() to prevent sensitive resources and their associated telemetry from being accessible to AI assistants.
• No persistent storage — the MCP server doesn’t write data to disk. All data is held in memory for the duration of the development session.
• Open specification — the MCP server implements the open Model Context Protocol specification, allowing security teams to review the protocol.

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.

AppHost detection and lifecycle

The Aspire MCP server automatically detects running AppHosts within the working directory scope. Understanding this lifecycle helps troubleshoot connection issues:

• When the MCP server starts (via aspire agent mcp), it scans for running AppHost processes.
• The MCP server continuously monitors for AppHost changes — you don’t need to restart the MCP server when starting or stopping AppHosts.
• Use list_apphosts to see which AppHosts are currently detected.
• Use select_apphost to switch between multiple running AppHosts.

Note

If your AI assistant doesn’t seem to detect your AppHost, verify it’s running with aspire run and that the AI assistant was started from (or has access to) the same workspace directory as your AppHost project.

Claude Code integration issues

If you experience issues with Claude Code and the Aspire MCP server:

• Verify configuration — ensure .mcp.json exists in your project root with the correct configuration. Run aspire agent init to regenerate it if needed.
• Windows cmd.exe prefix — on Windows, commands like npx require a cmd.exe /c prefix. See GitHub issue #14000 for details.
• Restart Claude Code — if the MCP server connection appears stale, restart Claude Code to re-establish the STDIO connection.
• Check Claude Code MCP logs — use Claude Code’s built-in MCP debugging to inspect connection status. Refer to the Claude Code MCP documentation for details.

Debugging MCP connection problems

If your AI assistant can’t connect to the Aspire MCP server:

1. Verify the Aspire CLI is installed and available on your PATH:

   Aspire CLI

   aspire --version

2. Confirm your AppHost is running:

   Aspire CLI

   aspire run

3. Test the MCP server directly by running it manually:

   Aspire CLI

   aspire agent mcp

   If the server starts without errors, the issue is likely in your AI assistant’s configuration.

4. Regenerate configuration files:

   Aspire CLI

   aspire agent init

5. Verify the generated configuration file matches your AI assistant’s expected format (see Understanding the configuration).

Deployment considerations

The Aspire MCP server is a development-time tool and should not be included in published or deployed applications. If your AppHost includes dev-only resources (such as MCP tooling or other development utilities), you may need to conditionally exclude them during deployment.

Exclude dev-only resources from publish

Use ExecutionContext.IsRunMode to conditionally add resources that should only be available during local development:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.Api>("api");

if (builder.ExecutionContext.IsRunMode)
{
    // Resources added here are only available during
    // local development with 'aspire run', and are
    // excluded from 'aspire deploy' and 'aspire publish'.
    builder.AddContainer("dev-tool", "some-dev-image");
}

builder.Build().Run();

Tip

The Aspire MCP server itself doesn’t require any explicit exclusion — it’s part of the Aspire CLI tooling and runs separately from your AppHost. This pattern is useful for other dev-only resources that might interfere with deployment, such as local monitoring tools or test containers.

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.

See also

• aspire agent command
• aspire agent init command
• aspire agent mcp command
• Dashboard security considerations
• GitHub Copilot in the Dashboard