This guide helps you diagnose and resolve common issues with the Azure MCP Server. For comprehensive authentication guidance, see our detailed Authentication guide.
By default, Azure MCP Server communicates with MCP Clients via standard I/O. Any logs output to standard I/O are subject to interpretation from the MCP Client. See Logging for information on how to view logs.
Yes, you can enable multiple MCP servers that only load the services you need. In this example, two MCP servers are registered that only expose storage and keyvault tools:
{
"servers": {
"Azure Storage": {
"type": "stdio",
"command": "<absolute-path-to>/azure-mcp/core/src/AzureMcp.Cli/bin/Debug/net9.0/azmcp[.exe]",
"args": [
"server",
"start",
"--namespace",
"storage"
]
},
"Azure KeyVault": {
"type": "stdio",
"command": "<absolute-path-to>/azure-mcp/core/src/AzureMcp.Cli/bin/Debug/net9.0/azmcp[.exe]",
"args": [
"server",
"start",
"--namespace",
"keyvault"
]
}
}
}The Azure MCP Server can run in multiple modes. Review your MCP configuration to ensure it matches your expectations:
azmcp server start- Launches an MCP server with all tools enabledazmcp server start --namespace <service-name>- Launches an MCP server with tools for the specified service (e.g.,storage,keyvault)azmcp server start --mode single- Launches an MCP server with a singleazuretool that performs internal dynamic proxy and tool selectionazmcp server start --mode namespace- Launches an MCP server with a tool registered for each Azure service/namespace.
When using the Azure MCP Server in VS Code, you may see a permission dialog requesting authorization for the MCP server to make language model calls:
The dialog shows: "The MCP server 'Azure' has issued a request to make an language model call. Do you want to allow it to make requests during chat?"
To continue using the Azure MCP Server, you must click one of the following:
- "Allow in this Session" - Allows the server to make language model calls for the current VS Code session
- "Always" - Permanently allows the server to make language model calls
This permission is required because some Azure MCP tools may need to make additional language model calls to process complex requests or provide enhanced responses.
Warning
Known Issue: "You may not include more than 128 tools in your request"
When configuring Azure MCP with 'all' toolsets, you may encounter this error:
VS Code Copilot has a 128-tool limit per request. Combining multiple comprehensive toolsets (like GitHub MCP 'all' + Azure MCP 'all') exceeds this limit. See the VS Code discussion for more details.
Option 1: Use VS Code Custom Chat Modes (Recommended)
VS Code supports custom chat modes for scenario-specific tool configurations:
Setup Steps:
- Install your desired MCP servers (Azure, GitHub, etc.)
- Create custom chat modes in VS Code for different workflows
- Switch between modes based on your current task
- Use the tool picker to discover and add tools as needed
- Stay within the 128-tool limit per mode while maintaining flexibility
Option 2: Use Selective Tool Loading
Configure targeted MCP servers for specific needs instead of loading all tools:
Example Configuration:
{
"servers": {
"Azure Storage": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@azure/mcp@latest", "server", "start", "--namespace", "storage"]
},
"Azure KeyVault": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@azure/mcp@latest", "server", "start", "--namespace", "keyvault"]
},
"GitHub Issues": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github@latest"]
}
}
}Result: ~15-20 tools total instead of 128+
Available Azure Services for --namespace flag:
See the complete list of Available Azure MCP Servers in the README.
You can start the server with multiple services by specifying after the --namespace flag, such as --namespace storage --namespace keyvault.
Option 3: Use Dynamic Tool Selection
Azure MCP's dynamic proxy mode exposes one tool that routes to all Azure services:
Example Configuration:
{
"servers": {
"Azure Dynamic": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@azure/mcp@latest", "server", "start", "--mode", "single"]
}
}
}Note
This counts as 1 tool but can access all Azure services. However, combining with other comprehensive toolsets may still hit the 128-tool limit.
- Open VS Code Command Palette (Ctrl+Shift+P)
- Run "MCP: List Servers"
- Check the tool count for each server in the output window
For comprehensive authentication guidance including advanced scenarios for protected resources, firewall restrictions, and enterprise environments, see our detailed Authentication guide.
This error indicates that the targeted resource is configured to disallow access using Access Keys, which Azure MCP uses for authentication in certain scenarios.
Azure MCP relies on access key-based authentication for some resources. However, many Azure services (e.g., Cosmos DB, Azure Storage) can be configured to enforce Azure Entra ID authentication only, disabling local authorization methods such as:
- Primary or secondary access keys
- Shared access signatures (SAS)
- Connection strings with embedded keys
When these methods are disabled, Azure MCP access attempts will result in a 401 Unauthorized error.
If you encounter this error in an enterprise environment, work with your resource administrator to:
-
Verify RBAC Permissions: Ensure your account has appropriate data plane roles:
- For Storage:
Storage Blob Data Reader,Storage Blob Data Contributor, orStorage Blob Data Owner - For Cosmos DB:
Cosmos DB Built-in Data Reader,Cosmos DB Built-in Data Contributor - For Key Vault:
Key Vault Secrets User,Key Vault Crypto User
- For Storage:
-
Confirm Authentication Method: Ask your administrator:
- "Is local authentication disabled on this resource?"
- "What RBAC roles are available for data plane access?"
- "Should I use user authentication or a service principal?"
-
Network Considerations: If the resource is behind a firewall or uses private endpoints:
- "Are there network restrictions I need to be aware of?"
- "Do I need VPN access to reach private endpoints?"
- "What IP addresses should be allowlisted for access?"
This error indicates that the access token doesn't have sufficient permissions to access the requested resource.
-
Insufficient RBAC Permissions
Ensure that the service principal or user principal has appropriate **Role-Based Access Control (RBAC)** permissions at the correct scope (resource group, subscription, or resource level). -
Incorrect Subscription or Tenant Context
Verify that the subscription and tenant are properly specified. When using an LLM (e.g., via Copilot Chat), provide explicit context:List all my storage accounts in subscription
<subscription-id-or-name>, located in tenant<tenant-id-or-name>. -
Unintended Account Being Used
If you have multiple accounts signed in, the authentication process may be using a different account than intended.To ensure the correct account is used, set this environment variable and restart both your IDE and the MCP server:
AZURE_MCP_ONLY_USE_BROKER_CREDENTIAL=true
This will prompt you to select your desired account for authentication.
When running Azure MCP Server in the VS Code context, you may encounter an authentication error like:
Authenticate: Bearer authorization_uri="https://login.windows.net/<Tenant>",
error="invalid_token",
error_description="The primary access token is from the wrong issuer.
It must match the tenant associated with this subscription.
Please use correct authority to get the token."
VS Code may default to a tenant different from the one associated with your Azure subscription. When the MCP Server requests a token, the issuer in that token must match the subscription's tenant. If they don't match, the request fails.
Specify the preferred tenant in your VS Code global settings.json file.
Steps:
-
Determine your correct Tenant ID:
az account show --query tenantId -o tsv
-
Add the following setting to the VS Code global settings file:
Stable (GA) VS Code
~/AppData/Roaming/Code/User/settings.json(Windows)~/Library/Application Support/Code/User/settings.json(macOS)~/.config/Code/User/settings.json(Linux)Insiders VS Code
~/AppData/Roaming/Code - Insiders/User/settings.json(Windows)~/Library/Application Support/Code - Insiders/User/settings.json(macOS)~/.config/Code - Insiders/User/settings.json(Linux) -
Restart VS Code and the Azure MCP Server.
Example:
{
"@azure.argTenant": "11111111-2222-3333-4444-555555555555"
}This ensures tokens are requested for the correct authority, matching the subscription's tenant, and resolves the invalid_token issuer mismatch.
Azure MCP Server requires network connectivity to Azure services and authentication endpoints. In enterprise environments with strict network controls, additional configuration may be needed.
-
Corporate Firewall Blocking Azure Endpoints
- Authentication fails with connection timeout errors
- Unable to reach
login.microsoftonline.comormanagement.azure.com
-
Proxy Server Configuration
- HTTP/HTTPS proxy not configured for Azure MCP Server
- Corporate proxy certificates not trusted
-
Private Endpoint Connectivity
- Resources configured with private endpoints require VPN or ExpressRoute access
- DNS resolution issues for private endpoint addresses
Essential Information to Provide:
-
Required Endpoints for Authentication:
login.microsoftonline.com:443 login.windows.net:443 management.azure.com:443 graph.microsoft.com:443 -
Resource-Specific Endpoints:
Storage: *.blob.core.windows.net:443, *.table.core.windows.net:443 Key Vault: *.vault.azure.net:443 Cosmos DB: *.documents.azure.com:443 Service Bus: *.servicebus.windows.net:443 -
Proxy Configuration (if applicable):
# Set these environment variables if using a corporate proxy export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=http://proxy.company.com:8080 export NO_PROXY=localhost,127.0.0.1
-
Test Basic Connectivity:
# Test authentication endpoint curl -I https://login.microsoftonline.com # Test resource management endpoint curl -I https://management.azure.com
-
Check Private Endpoint DNS Resolution:
# Should resolve to private IP (10.x.x.x) if using private endpoints nslookup mystorageaccount.blob.core.windows.net -
Verify Certificate Trust:
# Check if corporate certificates are trusted openssl s_client -connect login.microsoftonline.com:443 -servername login.microsoftonline.com
- Are there firewall rules blocking outbound HTTPS traffic to Azure endpoints?
- Is a corporate proxy server required for internet access?
- Are there Conditional Access policies affecting network access?
- Do Azure resources use private endpoints that require VPN access?
- Are corporate CA certificates properly installed and trusted?
Many enterprise environments have additional security controls that can affect Azure MCP Server authentication and operation.
In environments where interactive authentication isn't suitable or allowed:
-
Request Service Principal Creation: Ask your Azure administrator to create a service principal with this information:
Application Name: Azure MCP Server - [Your Name/Team] Required Permissions: - Reader role at subscription/resource group level - Data plane roles for specific resources (e.g., Storage Blob Data Reader) Justification: Development/testing with Azure MCP Server -
Configuration: Once created, configure these environment variables:
export AZURE_CLIENT_ID="service-principal-client-id" export AZURE_CLIENT_SECRET="service-principal-secret" export AZURE_TENANT_ID="your-tenant-id"
-
Certificate-Based Authentication (Preferred): For enhanced security, request certificate-based authentication:
export AZURE_CLIENT_ID="service-principal-client-id" export AZURE_CLIENT_CERTIFICATE_PATH="/path/to/certificate.pem" export AZURE_TENANT_ID="your-tenant-id"
Organizations may enforce Conditional Access policies that affect authentication:
Common Policy Requirements:
- Device compliance (Azure AD joined devices)
- Multi-factor authentication (MFA)
- Location-based restrictions
- Application-specific controls
Working with Identity Administrators:
-
Check Policy Impact:
Questions to ask:
- Are there Conditional Access policies affecting my authentication?
- Is my device compliant with organizational policies?
- Do I need to use a specific authentication method?
- Can I get an exception for development scenarios?
-
Policy Compliance Steps:
- Ensure your device is Azure AD joined or hybrid joined
- Complete device compliance enrollment if required
- Use compliant authentication methods (avoid saved credentials in non-compliant browsers)
- Connect from approved network locations if location policies exist
When resources are heavily restricted:
-
Minimum Required Information to Gather:
Resource Details:
- Resource names and types
- Resource group and subscription
- Whether private endpoints are used
- Network restrictions (IP allowlists, VNet integration)
Access Requirements:
- Required RBAC roles
- Network access requirements
- Authentication method preferences
-
Escalation Path:
Level 1: Resource Administrator
- Resource-specific permissions
- RBAC role assignments
Level 2: Network Administrator
- Firewall rules and network access
- Private endpoint connectivity
Level 3: Identity Administrator
- Conditional Access policies
- Service principal creation
This error occurs when trying to authenticate with a personal Microsoft account (@hotmail.com, @outlook.com, @live.com, @gmail.com, etc.) against Azure resources.
Azure MCP Server uses the Azure Identity SDK's DefaultAzureCredential for authentication, which requires Microsoft Entra ID credentials to access Azure resources. Personal Microsoft accounts use a different authentication system that isn't compatible with Azure resource access patterns.
See the Authentication guide for detailed information about supported authentication methods.
Option 1: Use an Organizational Account (Recommended)
- Switch to a work or school account that's part of a Microsoft Entra ID tenant
- Contact your organization's IT administrator to gain access to your company's Azure subscription
Option 2: Request Access to Existing Azure Subscription
- Ask your organization to add your work account to their Azure subscription
- Learn more: Add organization users and manage access
Option 3: Create a New Azure Subscription with Entra ID Tenant
- Create a new Azure subscription, which automatically creates a Microsoft Entra ID tenant
- This gives you full control but requires setting up your own Azure environment
- Learn more: Associate or add an Azure subscription to your Microsoft Entra tenant
Option 4: Create a Microsoft Entra ID Tenant for Your Personal Account
- If you must use a personal account, create a new Microsoft Entra ID tenant first
- Then associate your Azure subscription with this tenant
- Learn more:
- Choose the option that best fits your scenario
- Complete the authentication setup as described in the Authentication guide
- Verify access by running
az account showto confirm you're authenticated with the correct account type
The Azure MCP wrapper automatically installs the correct platform-specific package when needed. However, if you encounter persistent errors about missing platform packages (e.g., @azure/mcp-linux-x64, @azure/mcp-win32-x64, @azure/mcp-darwin-x64), this may indicate network connectivity issues or permission problems.
Failed to load platform specific package '@azure/mcp-linux-x64'Cannot find module '@azure/mcp-linux-x64''@azure/mcp-linux-x64' module is missing
First, ensure you have the latest VS Code version (v1.101 or later), as older versions may cause compatibility issues with the Azure MCP Server on Ubuntu systems.
The wrapper will attempt automatic installation first. If auto-installation fails, try these manual steps:
-
Clear npm cache and reinstall:
npm cache clean --force npm uninstall -g @azure/mcp npm install -g @azure/mcp@latest
-
If using npx, clear the cache:
npx clear-npx-cache npx -y @azure/mcp@latest server start
-
Manually install the platform package:
npm install @azure/mcp-linux-x64@latest # Linux x64 npm install @azure/mcp-darwin-x64@latest # macOS x64 npm install @azure/mcp-win32-x64@latest # Windows x64
-
Check your internet connection and try again
-
Verify Node.js and npm versions:
node --version # Should be 20.0.0 or later npm --version
- Network connectivity issues during package installation
- Permission problems preventing npm from installing packages
- Corporate firewall/proxy blocking npm registry access
- Disk space issues preventing package extraction
- npm cache corruption preventing proper package resolution
If you're behind a corporate firewall, you may need to:
- Configure npm proxy settings
- Whitelist npm registry domains (
*.npmjs.org,registry.npmjs.org) - Work with IT to ensure npm can download packages
The Azure MCP Server is instrumented using the .NET EventSource to emit detailed information. Logging follows the pattern of marking operation start, completion, and exceptions. These logs are invaluable for diagnosing Azure MCP Server issues.
Server logs can be obtained by capturing events for provider "Microsoft-Extensions-Logging".
dotnet-trace is a cross-platform CLI for collecting .NET Core traces:
- Install dotnet-trace
- Find the process ID for the server (azmcp.exe)
- Run:
dotnet-trace collect -p {your-process-id} --providers 'Microsoft-Extensions-Logging:4:5' - Collect the trace
- A
.nettracefile will be output
On Windows, use PerfView to visualize the .nettrace file. On other operating systems, use third-party tools.
For more information, see: Logging in .NET Core and ASP.NET Core: Event Source and Well-known event providers in .NET
By default, VS Code logs informational, warning, and error level messages. To get detailed interaction information:
- Open Command Palette (Ctrl+Shift+P)
- Search for "MCP: List Servers"
- Select "Azure MCP Server"
- Select "Show Output"
- Examine the "Output" window in VS Code
- Select "MCP: Azure MCP Server" from the dropdown menu
- Click "Set Log Level..." and choose "Trace" or "Debug"
PerfView is a free performance analysis tool for Windows:
- Download and open PerfView
- Select "Collect" file menu item then "Collect"
- Find the process ID for the server (azmcp.exe)
- Select "Focus process" checkbox and enter the process ID or executable name
- Expand "Advanced Options" section
- In "Additional Providers" list, add
*Microsoft-Extensions-Logging(include the*) - Press "Start Collection"
- Download and open PerfView
- In the file explorer, double-click to expand the
.nettracefile - Select the "Events" item
- Under Event Types, examine events under
Microsoft-Extensions-Logging/*
The server supports observability with OpenTelemetry.
To export telemetry to an OTLP endpoint, set the OTEL_DISABLE_SDK environment variable to false. By default, when OpenTelemetry is enabled, the server exports telemetry using the default gRPC endpoint at localhost:4317. See the OTLP exporter documentation for configuration details.
You can try it locally with the standalone Aspire dashboard:
docker run --rm -it -d \
-p 18888:18888 \
-p 4317:18889 \
--name aspire-dashboard \
mcr.microsoft.com/dotnet/aspire-dashboard:9.0To export telemetry to Azure Monitor, set the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable.
Bring your own language model key An existing API key from a language model provider can be used to access that provider’s models in VS Code chat, in addition to the built-in models available through Copilot. Supported providers include Anthropic, Azure, Google Gemini, Groq, Ollama, OpenAI, and OpenRouter.
The Azure MCP Server extension installs its platform-specific binaries in the user profile directory under:
<User-Profile-Dir>/.vscode/extensions/ms-azuretools.vscode-azure-mcp-server-<version>-<platform>/server
Examples:
- Windows:
C:\Users\<YourUserName>\.vscode\extensions\ms-azuretools.vscode-azure-mcp-server-1.0.0-win32-x64 - macOS:
/Users/<YourUserName>/.vscode/extensions/ms-azuretools.vscode-azure-mcp-server-1.0.0-darwin-x64 - Linux:
/home/<YourUserName>/.vscode/extensions/ms-azuretools.vscode-azure-mcp-server-1.0.0-linux-x64
This can be useful for:
- Verifying the exact version installed
- Checking platform-specific binaries
- Troubleshooting and replacing binaries in development builds