# azure/azure-mcp architecture

> Architecture diagram of the GitHub repository azure/azure-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure/azure-mcp
- Repository: https://github.com/azure/azure-mcp

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Client["Client<br/>(VS Code Copilot Agent / Custom MCP Client)"]:::client

    %% Distribution Layer
    subgraph "Distribution Layer"
        subgraph "Node.js Wrapper (eng/npm)" 
            WrapperIndex["index.js"]:::wrapper
            WrapperPlatform["platform/index.js"]:::wrapper
        end
        DockerfileNode["Dockerfile"]:::wrapper
    end

    %% Transport to Server
    Client -->|"npx @azure/mcp server start / Docker run"| WrapperIndex
    WrapperIndex -->|"STDIO / SSE JSON"| MCPServer

    %% .NET Server Layer
    subgraph ".NET MCP Server" 
        direction TB
        MCPServer["AzureMCP.exe<br/>(Program.cs)"]:::server
        ArgumentParser["Arguments Layer"]:::server
        CommandDispatcher["Command Dispatcher"]:::server
        ServiceLayer["Service Layer"]:::server
        CredentialChain["Authentication & Credential Chain"]:::server
        ExternalProcessService["ExternalProcessService"]:::server
        Models["Models (DTOs)"]:::server
    end

    %% Internal Flow
    MCPServer -->|"Input JSON"| ArgumentParser
    ArgumentParser -->|"Arguments objects"| CommandDispatcher
    CommandDispatcher -->|"Invoke Command"| ServiceLayer
    ServiceLayer -->|"Use Azure SDK / ExternalProcessService"| AzureSDK
    ServiceLayer -->|"Invoke az CLI / azd"| ExternalProcessService
    ExternalProcessService -->|"Process Exec"| AzureCLI["Azure CLI / azd"]:::external
    AzureSDK -->|"REST/gRPC calls"| AzureServices
    AzureCLI -->|"Provision/Manage Resources"| AzureServices
    ServiceLayer -->|"Return DTOs"| Models
    Models -->|"JSON response"| MCPServer

    MCPServer -->|"JSON response"| WrapperIndex
    WrapperIndex -->|"MCP JSON"| Client

    %% Azure SDK and Services
    subgraph "Azure SDK & Services"
        direction TB
        AzureSDK["Azure SDKs"]:::sdk
        AzureServices["Azure Services"]:::sdk
    end

    %% Infrastructure
    Infra["Infrastructure (Bicep IaC)"]:::infra

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        direction TB
        Pipelines["Build/Test/Publish"]:::pipelines
    end

    Pipelines -->|build/test/publish| WrapperIndex
    Pipelines -->|build/test/publish| MCPServer

    Infra -->|deploy test/prod resources| AzureServices

    %% Click Events
    click WrapperIndex "https://github.com/azure/azure-mcp/blob/main/eng/npm/wrapper/index.js"
    click WrapperPlatform "https://github.com/azure/azure-mcp/blob/main/eng/npm/platform/index.js"
    click DockerfileNode "https://github.com/azure/azure-mcp/tree/main/Dockerfile"
    click MCPServer "https://github.com/azure/azure-mcp/blob/main/src/Program.cs"
    click ArgumentParser "https://github.com/azure/azure-mcp/tree/main/src/Arguments/"
    click CommandDispatcher "https://github.com/azure/azure-mcp/blob/main/src/Commands/CommandFactory.cs"
    click CommandDispatcher "https://github.com/azure/azure-mcp/blob/main/src/Commands/BaseCommand.cs"
    click CommandDispatcher "https://github.com/azure/azure-mcp/blob/main/src/Commands/CommandGroup.cs"
    click ServiceLayer "https://github.com/azure/azure-mcp/tree/main/src/Services/Interfaces/"
    click ServiceLayer "https://github.com/azure/azure-mcp/tree/main/src/Services/Azure/"
    click ExternalProcessService "https://github.com/azure/azure-mcp/blob/main/src/Services/ProcessExecution/ExternalProcessService.cs"
    click CredentialChain "https://github.com/azure/azure-mcp/blob/main/src/Services/Azure/Authentication/CustomChainedCredential.cs"
    click CredentialChain "https://github.com/azure/azure-mcp/blob/main/src/Services/Azure/Authentication/TimeoutTokenCredential.cs"
    click CredentialChain "https://github.com/azure/azure-mcp/blob/main/src/Services/Azure/Authentication/WindowHandleProvider.cs"
    click Models "https://github.com/azure/azure-mcp/tree/main/src/Models/"
    click Infra "https://github.com/azure/azure-mcp/tree/main/infra/services/"
    click Pipelines "https://github.com/azure/azure-mcp/blob/main/eng/pipelines/ci.yml"
    click Pipelines "https://github.com/azure/azure-mcp/blob/main/eng/pipelines/pullrequest.yml"

    %% Styles
    classDef client fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef wrapper fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef server fill:#d5f5e3,stroke:#28a745,color:#000;
    classDef sdk fill:#ffe5b4,stroke:#ff8800,color:#000;
    classDef infra fill:#e0e0e0,stroke:#888888,color:#000;
    classDef pipelines stroke-dasharray: 5 5,fill:#ffffff,stroke:#999999,color:#000;
    classDef external fill:#f0f0f0,stroke:#666666,color:#000;
```
