# Azure MCP CLI Command Reference > [!IMPORTANT] > The Azure MCP Server has two modes: MCP Server mode and CLI mode. When you start the MCP Server with `azmcp server start` that will expose an endpoint for MCP Client communication. The `azmcp` CLI also exposes all of the tools via a command line interface, i.e. `azmcp subscription list`. In this document, "command" refers to CLI commands (e.g., `azmcp storage account list`), while "tool" refers to MCP server tools that can be invoked by MCP clients. ## Global Options The following options are available for all commands: | Option | Required | Default | Description | |-----------|----------|---------|-------------| | `--subscription` | No | Environment variable `AZURE_SUBSCRIPTION_ID` | Azure subscription ID for target resources | | `--tenant-id` | No | - | Azure tenant ID for authentication | | `--auth-method` | No | 'credential' | Authentication method ('credential', 'key', 'connectionString') | | `--retry-max-retries` | No | 3 | Maximum retry attempts for failed operations | | `--retry-delay` | No | 2 | Delay between retry attempts (seconds) | | `--retry-max-delay` | No | 10 | Maximum delay between retries (seconds) | | `--retry-mode` | No | 'exponential' | Retry strategy ('fixed' or 'exponential') | | `--retry-network-timeout` | No | 100 | Network operation timeout (seconds) | | `--learn` | No | false | Discover available sub-commands and their parameters without executing any Azure operation. Use on a command group to list commands in that group, or on a specific command to see its options. | ### Discovery with `--learn` The `--learn` flag enables AI agents and users to progressively discover the Azure MCP CLI without starting an MCP server. It works at every level of the command hierarchy: ```bash # List all commands available under the 'storage' namespace azmcp storage --learn # List all commands under 'storage account' azmcp storage account --learn # Show the options for a specific command without executing it azmcp storage account list --learn ``` The output is a JSON `CommandResponse` containing a list of `CommandInfo` objects with the command name, description, full CLI path, and all supported options. This is equivalent to the `learn` parameter supported by the Azure MCP server tools in namespace mode. ### CLI Logging In CLI mode, all `azmcp` commands write only JSON to **stdout**. Informational and diagnostic log messages are written to **stderr**. This means AI agents and tools consuming stdout receive clean JSON without log noise. To see logs while running a CLI command: ```powershell # Show logs in terminal alongside JSON output (PowerShell / bash) azmcp storage account list --subscription 2>&1 # Capture JSON silently, discard logs (PowerShell) $json = azmcp storage account list --subscription 2>$null # Write logs to a file while JSON goes to stdout azmcp storage account list --subscription 2>azmcp.log ``` ## Available Commands ### Server Operations The Azure MCP Server can be started in several different modes depending on how you want to expose the Azure tools: #### Using azmcp locally vs in container images The commands in this document assume you are running the **`azmcp` CLI locally** for example as a .NET global tool. In that case the executable is called `azmcp` and commands such as: ```bash azmcp server start --mode namespace --transport=stdio ``` are valid. When you run the **Azure MCP Server container image** `mcr.microsoft.com/azure-sdk/azure-mcp` (for example in Azure Container Apps), the image already contains an entrypoint that starts the MCP server process. The image does **not** support overriding the container command with `azmcp ...` directly, as the entrypoint is already configured to start the server. - Do **not** override the container command / entrypoint with `azmcp ...` when deploying the image. Doing so will cause the container to fail to start. - Leave the command / entrypoint blank in Azure Container Apps so the default image entrypoint is used. - If you need to customize the startup command or add extra arguments, build your own image based on the Azure MCP Server and set the ENTRYPOINT and/or CMD values in your Dockerfile there. That way you control exactly how the server starts without replacing the upstream image entrypoint at runtime. > [!NOTE] > ENTRYPOINT defines the executable that always runs; CMD provides > default arguments to that executable. Overriding the container command in > many PaaS providers replaces the image's ENTRYPOINT/CMD behavior, which can > break startup. The Azure MCP Server image ENTRYPOINT in the repository is: ```text ENTRYPOINT ["./server-binary", "server", "start"] ``` Because the image sets a fixed entrypoint, passing a container command such as `azmcp ...` will replace or conflict with that entrypoint. If you must change startup behavior, create a small derived Dockerfile that modifies the ENTRYPOINT/CMD as needed and deploy your custom image instead of overriding the command in the PaaS UI. For the exact Dockerfile used to build the image see: https://github.com/microsoft/mcp/blob/main/Dockerfile The remaining sections describe the different server modes that apply to both the CLI and the container image entrypoint. #### Default Mode (Namespace) Exposes Azure tools grouped by service namespace. Each Azure service appears as a single namespace-level tool that routes to individual operations internally. This is the default mode to reduce tool count and prevent VS Code from hitting the 128 tool limit. ```bash # Start MCP Server with namespace-level tools (default behavior) azmcp server start \ [--transport ] \ [--read-only] # Explicitly specify namespace mode azmcp server start \ --mode namespace \ [--transport ] \ [--read-only] ``` #### All Tools Mode Exposes all Azure tools individually. Each Azure service operation appears as a separate MCP tool. ```bash # Start MCP Server with all tools exposed individually azmcp server start \ --mode all \ [--transport ] \ [--read-only] ``` #### Single Tool Mode Exposes a single "azure" tool that handles internal routing across all Azure MCP tools. ```bash # Start MCP Server with single azure tool azmcp server start \ --mode single \ [--transport ] \ [--read-only] ``` #### Namespace Filtering Exposes only tools for specific Azure service namespaces. Use multiple `--namespace` parameters to include multiple namespaces. ```bash # Start MCP Server with only Storage tools azmcp server start \ --namespace storage \ --mode all \ [--transport ] \ [--read-only] # Start MCP Server with Storage and Key Vault tools azmcp server start \ --namespace storage \ --namespace keyvault \ --mode all \ [--transport ] \ [--read-only] ``` #### Specific Tool Filtering Exposes only specific tools by name, providing the finest level of granularity. The `--namespace` and `--tool` options cannot be used together. Use multiple `--tool` parameters to include multiple tools. Using `--tool` automatically switches to `all` mode. ```bash # Start MCP Server with default mode and only subscription and resource group tools azmcp server start \ --tool azmcp_subscription_list \ --tool azmcp_group_list \ [--transport ] \ [--read-only] # Start MCP Server with all mode and essential storage management tools azmcp server start \ --mode all \ --tool azmcp_storage_account_get \ --tool azmcp_storage_account_create \ --tool azmcp_storage_blob_get \ [--transport ] \ [--read-only] ``` #### Consolidated Mode Exposes carefully curated tools that group related Azure operations together based on common user workflows and tasks. This mode provides the optimal balance between discoverability and usability by organizing consolidated tools that combine multiple related operations. Each consolidated tool groups operations that are commonly used together: - **Resource management**: Groups operations by resource type and action (get, create, edit, delete) - **Workflow-based**: Organizes tools around common tasks (deployment, monitoring, security) - **Metadata-aligned**: Only groups commands with exactly the same toolMetadata values (destructive, idempotent, readOnly, etc.) **Benefits:** - **Better for AI agents**: Reduces decision complexity by presenting meaningful tool groupings - **Optimized tool count**: Well under VS Code's 128-tool limit - **Task-oriented**: Tools are named after user intents (e.g., `get_azure_databases_details`, `deploy_azure_resources_and_applications`) - **Maintains functionality**: All individual commands are still accessible through the consolidated tools ```bash # Start MCP Server with consolidated mode azmcp server start \ --mode consolidated \ [--transport ] \ [--namespace ] \ [--read-only] ``` **Configuration file location**: The consolidated tool definitions are maintained in `core/Azure.Mcp.Core/src/Areas/Server/Resources/consolidated-tools.json`. Each definition includes: - Tool name and description optimized for AI agent selection - List of mapped individual commands - Matching toolMetadata (destructive, idempotent, readOnly, secret, etc.) #### Namespace Mode (Default) Collapses all tools within each namespace into a single tool (e.g., all storage operations become one "storage" tool with internal routing). This mode is particularly useful when working with MCP clients that have tool limits - for example, VS Code only supports a maximum of 128 tools across all registered MCP servers. ```bash # Start MCP Server with service proxy tools azmcp server start \ --mode namespace \ [--transport ] \ [--read-only] ``` #### Single Tool Proxy Mode Exposes a single "azure" tool that handles internal routing across all Azure MCP tools. ```bash # Start MCP Server with single Azure tool proxy azmcp server start \ --mode single \ [--transport ] \ [--read-only] ``` > **Note:** > > - For namespace mode, replace `` with available top level command groups. Run `azmcp -h` to review available namespaces. Examples include `storage`, `keyvault`, `cosmos`, `monitor`, etc. > - The `--read-only` flag applies to all modes and filters the tool list to only contain tools that provide read-only operations. > - Multiple `--namespace` parameters can be used together to expose tools for multiple specific namespaces. > - The `--namespace` and `--mode` parameters can also be combined to provide a unique running mode based on the desired scenario. #### Server Start Command Options The `azmcp server start` command supports the following options: | Option | Required | Default | Description | |--------|----------|---------|-------------| | `--transport` | No | `stdio` | Transport mechanism to use. Valid values: `stdio` (default, supported in all distributions) or `http` (supported only in the Docker image distribution and other builds with HTTP enabled; may not be available in local CLI builds). | | `--mode` | No | `namespace` | Server mode: `namespace` (default), `consolidated`, `all`, or `single` | | `--namespace` | No | All namespaces | Specific Azure service namespaces to expose (can be repeated). Works with all existing modes to filter tools. | | `--tool` | No | All tools | Expose specific tools by name (e.g., 'azmcp_storage_account_get'). It automatically switches to `all` mode. It can't be used together with `--namespace`. | | `--read-only` | No | `false` | Only expose read-only operations | | `--debug` | No | `false` | Enable verbose debug logging to stderr | | `--dangerously-disable-http-incoming-auth` | No | false | Dangerously disable HTTP incoming authentication | | `--dangerously-disable-elicitation` | No | `false` | **⚠️ DANGEROUS**: Disable user consent prompts for sensitive operations | | `--outgoing-auth-strategy` | No | `NotSet` | Outgoing authentication strategy for service requests. Valid values: `NotSet`, `UseHostingEnvironmentIdentity`, `UseOnBehalfOf`. | | `--dangerously-write-support-logs-to-dir` | No | - | **⚠️ DANGEROUS**: Enables detailed debug-level logging for support and troubleshooting. Specify a folder path where log files will be created with timestamp-based filenames. May include sensitive information in logs. | | `--cloud` | No | `AzureCloud` | Azure cloud environment for authentication. Valid values: `AzureCloud` (default), `AzureChinaCloud`, `AzureUSGovernment`, or a custom authority host URL starting with `https://`. When a custom authority host URL is used, only the authentication authority host is changed; ARM and other service endpoints continue to use the Azure public cloud. | | `--disable-caching` | No | `false` | Disable caching of resource responses, requiring repeated requests to fetch fresh data each time. | > **⚠️ Security Warning for `--dangerously-disable-elicitation`:** > > This option disables user confirmations (elicitations) before running tools that read sensitive data. When enabled: > - Tools that handle secrets, credentials, or sensitive data will execute without user confirmation > - This removes an important security layer designed to prevent unauthorized access to sensitive information > - Only use this option in trusted, automated environments where user interaction is not possible > - Never use this option in production environments or when handling untrusted input > > **Example usage (use with caution):** > ```bash > # For automated scenarios only - bypasses security prompts > azmcp server start --dangerously-disable-elicitation > ``` > **⚠️ Security Warning for `--dangerously-write-support-logs-to-dir`:** > > This option enables detailed debug-level logging that may include sensitive information such as request payloads and authentication details. When enabled: > - Log files are created in the specified directory with timestamp-based filenames (e.g., `azmcp_20251202_143052.log`) > - Logs may contain sensitive data that could be useful for support troubleshooting > - Only use this option when specifically requested by support for diagnosing issues > - Remove log files after troubleshooting is complete > > **Example usage:** > ```bash > # For support troubleshooting only > azmcp server start --dangerously-write-support-logs-to-dir /path/to/logs > ``` > **Note on `--outgoing-auth-strategy`:** > > This option controls how the server authenticates when making requests to downstream Azure services: > - `NotSet` (default): A safe default is chosen based on other settings > - `UseHostingEnvironmentIdentity`: Uses the hosting environment's identity (similar to `DefaultAzureCredential`). All outgoing requests use the same identity regardless of the incoming request's identity > - `UseOnBehalfOf`: Exchanges the incoming request's access token for a new token valid for the downstream service. Only valid when the server is running with HTTP transport and incoming HTTP authentication enabled (i.e., `--transport http` without `--dangerously-disable-http-incoming-auth`) > **Note on `--cloud`:** > > Use this option to target sovereign cloud environments: > - `AzureCloud` (default): Azure public cloud > - `AzureChinaCloud`: Azure China (operated by 21Vianet) > - `AzureUSGovernment`: Azure US Government > - Custom URL: A custom authority host URL starting with `https://` > > **Example usage:** > ```bash > # Connect to Azure US Government cloud > azmcp server start --cloud AzureUSGovernment > ``` #### Server Info ```bash # Get information about the MCP server, which includes the server's name and version. azmcp server info ``` ### Azure Advisor Operations ```bash # List Advisor recommendations in a subscription # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired azmcp advisor recommendation list --subscription ``` ### Azure AI Search Operations ```bash # Get detailed properties of AI Search indexes # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired azmcp search index get --service \ [--index ] # Query AI Search index # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired azmcp search index query --subscription \ --service \ --index \ --query # Get AI Search knowledge bases (all or a specific one) # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired azmcp search knowledge base get --service [--knowledge-base ] # Run retrieval against an AI Search knowledge base # ❌ Destructive | ✅ Idempotent | ✅ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired azmcp search knowledge base retrieve --service \ --knowledge-base \ [--query ] \ [--messages ] # Get AI Search knowledge sources (all or a specific one) # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired azmcp search knowledge source get --service [--knowledge-source ] # List AI Search accounts in a subscription # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired azmcp search service list --subscription \ [--resource-group ] ``` ### Azure AI Services Speech Operations ```bash # Recognize speech from an audio file using Azure AI Services Speech # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ✅ LocalRequired azmcp speech stt recognize --endpoint \ --file \ [--language ] \ [--phrases ] \ [--format ] \ [--profanity ] ``` #### Phrase Hints for Improved Accuracy The `--phrases` parameter supports multiple ways to specify phrase hints that improve speech recognition accuracy: **Multiple Arguments:** ```bash # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ✅ LocalRequired azmcp speech stt recognize --endpoint --file audio.wav \ --phrases "Azure" --phrases "cognitive services" --phrases "machine learning" ``` **Comma-Separated Values:** ```bash # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ✅ LocalRequired azmcp speech stt recognize --endpoint --file audio.wav \ --phrases "Azure, cognitive services, machine learning" ``` **Mixed Syntax:** ```bash # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ✅ LocalRequired azmcp speech stt recognize --endpoint --file audio.wav \ --phrases "Azure, cognitive services" --phrases "machine learning" ``` Use phrase hints when you expect specific terminology, technical terms, or domain-specific vocabulary in your audio content. This significantly improves recognition accuracy for specialized content. ```bash # Synthesize speech from text and save to an audio file using Azure AI Services Speech # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ❌ ReadOnly | ❌ Secret | ✅ LocalRequired azmcp speech tts synthesize --endpoint \ --text \ --outputAudio \ [--language ] \ [--voice ] \ [--format ] \ [--endpointId ] ``` #### Text-to-Speech Parameters | Parameter | Required | Description | |-----------|----------|-------------| | `--endpoint` | Yes | Azure AI Services endpoint URL (e.g., https://your-service.cognitiveservices.azure.com/) | | `--text` | Yes | The text to convert to speech | | `--outputAudio` | Yes | Path where the synthesized audio file will be saved (e.g., output.wav, speech.mp3) | | `--language` | No | Speech synthesis language (default: en-US). Examples: es-ES, fr-FR, de-DE | | `--voice` | No | Neural voice to use (e.g., en-US-JennyNeural, es-ES-ElviraNeural). If not specified, default voice for the language is used | | `--format` | No | Output audio format (default: Riff24Khz16BitMonoPcm). Supported formats: Riff24Khz16BitMonoPcm, Audio16Khz32KBitRateMonoMp3, Audio24Khz96KBitRateMonoMp3, Ogg16Khz16BitMonoOpus, Raw16Khz16BitMonoPcm | | `--endpointId` | No | Endpoint ID of a custom voice model for personalized speech synthesis | #### Supported Audio Formats The `--format` parameter accepts the following values: - **WAV formats**: `Riff24Khz16BitMonoPcm` (default), `Riff16Khz16BitMonoPcm`, `Raw16Khz16BitMonoPcm` - **MP3 formats**: `Audio16Khz32KBitRateMonoMp3`, `Audio24Khz96KBitRateMonoMp3`, `Audio48Khz192KBitRateMonoMp3` - **OGG/Opus formats**: `Ogg16Khz16BitMonoOpus`, `Ogg24Khz16BitMonoOpus` **Examples:** ```bash # Basic text-to-speech synthesis # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ❌ ReadOnly | ❌ Secret | ✅ LocalRequired azmcp speech tts synthesize --endpoint https://myservice.cognitiveservices.azure.com/ \ --text "Hello, welcome to Azure AI Services Speech" \ --outputAudio welcome.wav # Synthesize with specific language and voice # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ❌ ReadOnly | ❌ Secret | ✅ LocalRequired azmcp speech tts synthesize --endpoint https://myservice.cognitiveservices.azure.com/ \ --text "Hola, bienvenido a los servicios de voz de Azure" \ --outputAudio spanish-greeting.wav \ --language es-ES \ --voice es-ES-ElviraNeural # Generate MP3 output with high quality # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ❌ ReadOnly | ❌ Secret | ✅ LocalRequired azmcp speech tts synthesize --endpoint https://myservice.cognitiveservices.azure.com/ \ --text "This is a high quality audio output" \ --outputAudio output.mp3 \ --format Audio48Khz192KBitRateMonoMp3 # Use custom voice model # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ❌ ReadOnly | ❌ Secret | ✅ LocalRequired azmcp speech tts synthesize --endpoint https://myservice.cognitiveservices.azure.com/ \ --text "This uses my custom trained voice" \ --outputAudio custom-voice.wav \ --voice my-custom-voice-model --endpointId my-custom-voice-endpoint-id ``` ### Azure App Configuration Operations ```bash # List App Configuration stores in a subscription # ❌ Destructive | ✅ Idempotent | ❌ OpenWorld | ✅ ReadOnly | ❌ Secret | ❌ LocalRequired azmcp appconfig account list --subscription \ [--resource-group ] # Delete a key-value setting # ✅ Destructive | ✅ Idempotent | ❌ OpenWorld | ❌ ReadOnly | ❌ Secret | ❌ LocalRequired azmcp appconfig kv delete --subscription \ --account \ --key \ [--label