How azure/azure-mcp works
Project type and purpose
• This is a hybrid full-stack CLI/server application (“Azure MCP Server”) implementing the Model Context Protocol (MCP) to translate natural-language agent requests into Azure service operations.
• It uses a Node.js “wrapper” for packaging/distribution (eng/npm) and a core .NET 7 application (src/*.cs) implementing the MCP server over STDIO or SSE, invoking Azure SDKs to manage resources.
File structure
Top-level folders:
• eng/npm → Node.js wrapper and platform bindings for NPX distribution
• src → .NET project with clear layered architecture
– Arguments → defines command-line argument models
– Commands → command implementations, grouped by Azure service
– Services → service abstractions and Azure SDK wrappers
– Models → DTOs for commands, arguments, responses
– Helpers/Extensions → cross-cutting helpers & telemetry
– Program.cs → entrypoint hosting MCP server (SSE/STDIO)
• infra → Bicep IaC for deploying Azure test or production resources
• eng/pipelines → CI/CD YAML templates for build/test/release
• tests → xUnit tests exercising arguments, commands, services
Configuration files: Dockerfile, Directory.Build.props, package.json under eng/npm.
Additional insights from README
• MCP server speaks JSON over STDIO or SSE.
• Supports both NPX-based startup (Node wrapper) and Docker.
• Relies on Azure.Identity.DefaultAzureCredential chain.
• Exposes tools for many Azure services (Storage, Cosmos, Kusto, AppConfig, KeyVault, etc.) via natural-language prompts.
Main components and interactions
1. Client (VS Code Copilot Agent or custom MCP client)
2. Node.js Wrapper (eng/npm/index.js)
3. .NET MCP Server (AzureMCP.exe / Program.cs)
– Argument Parser (Arguments layer)
– Command Dispatcher (CommandFactory + Commands)
– Service Layer (I*Service interfaces + Azure*Service implementations)
– Caching & Credential Chain (Azure.Identity via DefaultAzureCredential)
– ExternalProcessService (for invoking Azure CLI / azd)
4. Azure SDKs (Azure.Storage, Azure.Cosmos, Azure.Data.Tables, etc.)
5. Azure Services (Storage Accounts, Cosmos DB, Kusto, AppConfig, KeyVault, etc.)
6. Infrastructure (optional) – Bicep templates under infra/services for test-resource provisioning
7. CI/CD Pipeline (GitHub Actions / Azure Pipelines in eng/pipelines)
b. Relationships / Data flow
• Client → Wrapper: “npx @azure/mcp server start” or Docker run invokes Node process
• Wrapper ↔ .NET Server:
– STDIO or SSE transport carries JSON-encoded MCP requests/responses
• .NET Server internal flow:
1. Input JSON → Argument Parser → CommandFactory
2. Command → invokes Service Layer
3. Service Layer → Azure SDK / ExternalProcessService
4. SDK calls → Azure Resource endpoints
5. Response → Models → JSON → back to client
• CI/CD pipelines orchestrate build/test/publish of both Node wrapper and .NET server
c. Architectural patterns & principles
– Layered/Clean Architecture: separation of CLI layer (Arguments/Commands), business logic (Services), external dependencies (Azure SDK)
– Dependency Injection: I*Service interfaces for testability
– Single Responsibility: each command/service handles one Azure resource domain
– Transport abstraction: STDIO vs SSE in Program.cs
– Credential chain and caching for authentication resilience
d. Technologies & frameworks
– .NET 7 / C# / System.CommandLine
– Azure SDK for .NET (Storage, Cosmos, Tables, DataExplorer, AppConfiguration, KeyVault, etc.)
– Azure.Identity.DefaultAzureCredential
– Node.js for NPX packaging and CLI entrypoint
– Docker for containerized execution
– Bicep for IaC
– GitHub Actions / Azure Pipelines for CI/CD
Diagramming recommendations
– Client → Wrapper → Server (transport)
– Internally: Parser → Dispatcher → Service Layer → Azure SDK → Azure
– Server ↔ ExternalProcessService → Azure CLI / azd
– Pipelines → build/publish → Wrapper & Server images/packages
• Layers within the server: “Arguments”, “Commands”, “Services”, “Models”, “Credential chain”
Capturing essential elements
• Be explicit about the dual-runtime nature (Node + .NET).
• MCP transport abstraction (STDIO vs SSE).
• Service abstractions and use of Azure SDK.
• Don’t forget the authentication chain (DefaultAzureCredential).
• Distribution and packaging layer (eng/npm, Dockerfile).