Azure API MCP

A secure MCP (Model Context Protocol) server that provides controlled access to Azure CLI commands for LLM agents.

Features

• Multi-layer Security Validation: Basic security checks, configurable security policy, and read-only mode
• Flexible Authentication: Support for workload identity, managed identity, service principals, and existing Azure CLI sessions
• Embedded Configuration: Config files embedded in binary, no external dependencies required
• Local stdio transport: Runs only as a local subprocess of an MCP client
• Timeout Control: Configurable command execution timeouts
• Structured Error Handling: Detailed error information and types

Quick Start

Prerequisites

• Go 1.24 or higher
• Azure CLI (az) installed and in PATH

Installation

go build -o bin/azure-api-mcp ./cmd/server

Running

# Default mode (stdio transport)
./bin/azure-api-mcp

# Enable read-only mode
./bin/azure-api-mcp --readonly=true

# With security policy
./bin/azure-api-mcp --enable-security-policy --security-policy-file configs/security-policy.yaml

Authentication

The server supports multiple Azure authentication methods:

Auto-detection (default)

Tries in the following order:

1. Workload Identity
2. Managed Identity
3. Existing Azure CLI session

Explicit Configuration

Specify authentication method via environment variables:

# Workload Identity
AZ_AUTH_METHOD=workload-identity \
  AZURE_TENANT_ID=xxx \
  AZURE_CLIENT_ID=xxx \
  AZURE_FEDERATED_TOKEN_FILE=/path/to/token \
  ./bin/azure-api-mcp

# Managed Identity
AZ_AUTH_METHOD=managed-identity ./bin/azure-api-mcp

# Service Principal
AZ_AUTH_METHOD=service-principal \
  AZURE_TENANT_ID=xxx \
  AZURE_CLIENT_ID=xxx \
  AZURE_CLIENT_SECRET=xxx \
  ./bin/azure-api-mcp

# Skip automatic authentication setup
AZ_API_MCP_SKIP_AUTH_SETUP=true ./bin/azure-api-mcp

MCP Tool

call_az

The primary tool for executing Azure CLI commands.

Parameters:

• cli_command (string, required): The Azure CLI command to execute
• timeout (number, optional): Command timeout in seconds, default 120

Examples:

• Show storage account: cli_command="az storage account show --name myaccount"
• List AKS clusters: cli_command="az aks list"
• With timeout: cli_command="az vm list", timeout=60

Configuration Options

Command Line Flags

# Transport mode
--transport string          Transport mode: stdio only (default "stdio")

# Security configuration
--readonly                 Enable read-only mode (default false)
--readonly-patterns-file   Custom read-only patterns file
--enable-security-policy   Enable security policy validation
--security-policy-file     Custom security policy file

# Authentication
--auth-method string       Authentication method: auto, workload-identity, managed-identity, service-principal (default "auto")

# Other options
--timeout int              Timeout for command execution in seconds (default 120)
--log-level string         Log level: debug, info, warn, error (default "info")

Environment Variables

# Authentication
AZ_AUTH_METHOD=auto|workload-identity|managed-identity|service-principal
AZ_API_MCP_SKIP_AUTH_SETUP=true|false
AZURE_TENANT_ID=xxx
AZURE_CLIENT_ID=xxx
AZURE_CLIENT_SECRET=xxx
AZURE_FEDERATED_TOKEN_FILE=/path/to/token
AZURE_SUBSCRIPTION_ID=xxx

Security Architecture

Important Security Notes

This MCP server executes Azure CLI commands provided by LLM. While multiple validation layers are implemented, LLM may generate unexpected commands or discover validation bypasses. We strongly recommend:

1. Run locally through stdio - Configure an MCP client to start this binary as a local subprocess. Do not expose it through a network proxy or gateway.
2. Use agent frameworks with intervention handlers - Require explicit user approval before executing commands.
3. Apply principle of least privilege - Grant minimal permissions and enable security controls.

Foundation: Azure RBAC

The authoritative authorization boundary is Azure RBAC for the identity used by the local Azure CLI process.

Example: An agent with Azure Reader role can only perform read operations regardless of application configuration, while an agent with Contributor role on a specific resource group can only affect resources within that scope.

Application-level Validation (Three-tier System)

1. Basic Security (always enforced)

   • Must start with "az "
   • Blocks shell operators: |, >, <, &&, ||, ;, $, `, newlines
   • Prevents path traversal: ../ and ..\

2. Security Policy (optional, via --enable-security-policy)

   • Deny-list defined in configs/security-policy.yaml
   • Blocks dangerous operations such as:

     - az login
     - az logout
     - az group delete
     - az ad user delete
     

3. Read-Only Mode (optional, via --readonly=true)

   • Allow-list defined in configs/readonly-operations.yaml
   • Only permits safe read operations: list, show, get-, check-, describe, query
   • Includes extended list-* discovery commands (e.g. az vm list-sizes, az vm list-skus) via generalized list-[a-z-]+ pattern
   • Must explicitly enable (--readonly=true) to restrict to read operations only

Development

Testing

# Run all tests
go test ./...

# Run specific package tests
go test ./pkg/azcli/...

# Run with verbose output
go test -v ./...

# Run integration tests (requires Azure CLI setup)
go test -v -tags=integration ./pkg/azcli/...

Code Quality

# Format code
go fmt ./...

# Static analysis
go vet ./...
staticcheck ./...

Contributing

Contributions are welcome! Please see SECURITY.md for security issue reporting guidelines.