How to Use Azure MCP Server with Docker

Direct answer: Run Azure MCP Server as a local container process and connect your MCP client to the container over the transport supported by the server invocation. Docker provides an isolated execution boundary; it does not replace Microsoft Entra authentication or Azure RBAC. Sign in with a supported Azure credential, restrict the namespaces and tools you expose, and use read-only mode when it meets the task.

Microsoft documents Azure MCP Server as an MCP implementation that lets compatible clients and agents call tools for Azure resources. Its tools operate with Azure Identity and the permissions assigned to the signed-in identity. See the Azure MCP Server overview and tools reference.

1. Understand the components

The workflow has four parts:

• MCP host or client: an MCP-capable editor, agent, or application such as GitHub Copilot agent mode.
• Azure MCP Server: the MCP server process that exposes Azure-related tools.
• Docker: the local packaging and isolation boundary for that process.
• Azure: the subscriptions, resource groups, and resources accessed by tool calls.

The client sends MCP requests to the server. The server authenticates to Azure and performs only the operations allowed by the identity’s RBAC permissions and the tools you enabled.

2. Prerequisites and safety boundaries

• Docker installed on the development machine.
• An MCP client that can launch a local server over its supported transport.
• An Azure account with the subscription and resource permissions required for your tasks.
• A supported Azure Identity sign-in method, commonly Azure CLI authentication or managed identity.
• The current Azure MCP Server container image, tag, startup arguments, and client configuration from Microsoft’s official repository or release documentation.

The retrieved Microsoft documentation does not establish a current image name, tag, or exact local Docker command. Do not copy an image reference from an old blog post. Verify those volatile values immediately before use.

Microsoft’s security guidance recommends a trusted workstation or container, least-privilege RBAC, restricted filesystem and network access, a narrow tool surface, current dependencies, and confirmation for sensitive actions. Microsoft also states: Don’t use a local Azure MCP Server to handle production data or production credentials. Read the secure deployment guidance before connecting a container to an account with broad access.

3. Choose identity before starting the container

Azure CLI credential

For local development, sign in with Azure CLI on the host and make that credential available using the method supported by the current server image. The tools reference lists Azure CLI authentication as a default credential option. A container does not automatically inherit the host’s Azure session; follow the image documentation for credential mounting or environment configuration.

# Host-side preparation
az login
az account set --subscription "YOUR_SUBSCRIPTION_ID"
az account show

Set AZURE_SUBSCRIPTION_ID when the server or client needs an explicit subscription and the current invocation supports that environment variable:

export AZURE_SUBSCRIPTION_ID="YOUR_SUBSCRIPTION_ID"

Managed identity

Managed identity is generally associated with an Azure-hosted deployment. It is not created merely by running Docker on a laptop. If your container runs on an Azure host with an assigned identity, configure the server according to its current documentation and grant that identity only the required RBAC roles.

On-behalf-of authentication

Microsoft’s remote hosting guide uses an on-behalf-of (OBO) flow with Azure Container Apps. OBO passes a delegated token for the signed-in user to downstream Azure operations; it does not grant that user permissions they do not already have. OBO is a remote HTTPS deployment pattern, not the same as a local stdio container.

4. Run the server container without guessing an image tag

Use the following template after obtaining the current image reference and startup arguments from the official Azure MCP Server repository. The variable keeps the unverified value out of your configuration files.

# Replace this with the image and tag documented by Microsoft.
export AZURE_MCP_IMAGE="YOUR_VERIFIED_AZURE_MCP_IMAGE:TAG"

# Keep the process attached to stdin/stdout for an MCP stdio client.
docker run --rm -i \
  --name azure-mcp-server \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  -e AZURE_SUBSCRIPTION_ID \
  "$AZURE_MCP_IMAGE"

Do not add flags shown here if the verified image requires a writable directory, a different entrypoint, or a different transport. Add only the credential mounts, environment variables, namespaces, and tool-selection flags documented for that release.

Why stdio is normally used locally

The tools reference lists stdio as the default transport. In a local workflow, the MCP client starts Docker and exchanges protocol messages through the process’s standard input and output. Do not publish the container port or bind it to all interfaces unless you are intentionally implementing a remote transport and have authentication and network controls in place.

5. Connect an MCP client

Every MCP client has its own configuration format. The conceptual configuration is a command that starts Docker with an interactive stdin stream and the verified image. For clients that accept JSON server definitions, the shape is typically:

{
  "mcpServers": {
    "azure": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--name", "azure-mcp-server-client",
        "YOUR_VERIFIED_AZURE_MCP_IMAGE:TAG"
      ],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "YOUR_SUBSCRIPTION_ID"
      }
    }
  }
}

Adapt the property names to your client and include the credential settings required by the image. Keep protocol output on stdout; send diagnostic logging to stderr if the server supports a log option.

6. Limit namespaces, tools, and write access

The Azure MCP Server tools reference describes controls for server mode, namespaces, read-only operation, individual tool selection, and transport. Start with the smallest surface:

1. List the Azure task you need to automate.
2. Enable only the namespace needed for that task.
3. Select individual tools where the server supports it.
4. Use read-only mode for discovery, inventory, and reporting.
5. Require user confirmation for changes, deletion, role assignments, or other high-impact actions.

Tool filtering and RBAC solve different problems. A hidden tool cannot be called by the client, while RBAC limits what the Azure identity can do if a tool is enabled. Use both controls.

7. Subscription and resource-group context

The server can resolve a subscription from the Azure CLI profile or AZURE_SUBSCRIPTION_ID. Most operations also need a subscription or resource-group context. When a tool reports that a subscription or resource group is missing:

• Confirm the ID is correct and belongs to the signed-in tenant.
• Set the subscription explicitly instead of relying on a stale CLI default.
• Pass the resource group required by the specific tool.
• Check that the identity has access at the subscription or resource-group scope.

8. Local Docker versus remote Azure Container Apps

Decision	Local Docker	Azure Container Apps
Process location	Your trusted workstation or development container	Azure-hosted remote service
Typical client connection	Local stdio process	HTTPS endpoint
Authentication pattern	Azure CLI credential or managed identity, as supported by the invocation	Microsoft’s documented OBO template
Operational ownership	You manage Docker, credentials, and local isolation	You manage the Azure deployment, identity, ingress, and secrets
Best fit	Development and controlled experiments	Shared or remotely reachable integrations that need a hosted endpoint

Use Microsoft’s Container Apps deployment guidance when you need HTTPS and a remote service. Treat that deployment as a separate architecture with its own authentication and network review.

9. Troubleshooting by layer

Container exits immediately

Cause: wrong image, tag, entrypoint, or required argument.

Fix: run the verified image interactively, inspect Docker’s exit output, and compare the entrypoint and flags with the current official repository. Do not infer flags from another release.

The MCP client shows no tools

Cause: the client cannot start the command, Docker is not on its PATH, stdio is not passed through, or the server failed before completing MCP initialization.

Fix: run the exact Docker command outside the client, verify that stdin remains open, and inspect client and container stderr logs.

Authentication or credential errors

Cause: the container cannot see the selected Azure credential, the token belongs to another tenant, or the credential method is unsupported by the image.

Fix: confirm the supported Azure Identity method, tenant, and subscription. A host-side az login does not by itself make credentials available inside a container.

Subscription not found

Cause: no active CLI subscription or missing AZURE_SUBSCRIPTION_ID.

Fix: select the subscription with Azure CLI or pass the environment variable explicitly, then verify the identity can read that subscription.

AuthorizationFailed or forbidden responses

Cause: Azure RBAC does not grant the requested action at the required scope.

Fix: identify the exact resource and action, request the narrowest suitable role at the smallest scope, and retry after role-assignment propagation.

Network timeouts

Cause: Docker network restrictions, a proxy requirement, private endpoints, DNS failure, or blocked outbound access.

Fix: test DNS and HTTPS from the container, configure the documented proxy settings, and allow only the endpoints required for Azure authentication and APIs. Avoid using host networking as a blanket fix.

Unexpected write operations

Cause: a write-capable namespace or tool was enabled when read-only behavior was expected.

Fix: enable read-only mode, remove write tools, reduce RBAC permissions, and keep client confirmation enabled for sensitive calls.

10. Performance, reliability, and cost

• Startup: keeping the client and container process alive avoids repeated image startup overhead. Pull the verified image before a session rather than during a latency-sensitive action.
• Resource limits: set CPU, memory, process, and filesystem limits appropriate to your workstation. A read-only root filesystem and dropped capabilities reduce the blast radius of a compromised process.
• Retries: retry transient Azure API or network failures with bounded backoff. Do not blindly retry non-idempotent write operations.
• Observability: preserve stderr logs, Docker exit codes, MCP initialization errors, Azure request IDs, and the selected subscription when diagnosing failures. Remove tokens and secrets from logs.
• Credential lifetime: prefer short-lived tokens and avoid baking credentials into images or committing them to client configuration.
• Cost: Docker itself does not grant Azure access or eliminate Azure service charges. Azure costs depend on the resources and operations your tools invoke; check the pricing for those Azure services.

11. Checklist for a safe local setup

• Verified the current Azure MCP Server image, tag, entrypoint, and flags from Microsoft’s repository.
• Confirmed the MCP client supports the selected transport, usually local stdio.
• Signed in with the intended tenant and subscription.
• Granted only the RBAC roles required for the task.
• Enabled only required namespaces and tools.
• Selected read-only mode where possible.
• Restricted filesystem, network, Linux capabilities, and container privileges.
• Kept confirmation enabled for destructive or sensitive operations.
• Excluded production data and production credentials from local testing.
• Recorded a rollback path before enabling write operations.

12. Or skip the browser setup

If your task is collecting website screenshots for documentation, issue reports, or agent context, ScreenshotNeo provides a separate screenshot API and MCP server. One request returns a PNG, JPEG, WebP, or PDF. It handles cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and each response reports its verdict and billing status in headers.

See the ScreenshotNeo API documentation for all options.

# cURL
curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

# Python
import requests
r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

# Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. Plans include 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

13. FAQ

Does Docker authenticate to Azure?

No. Docker runs the process. Azure Identity and the configured credential authenticate requests, and RBAC authorizes them.

Can I expose the local server to the internet?

Do not expose a local server casually. Use a separately designed hosted deployment with HTTPS, authentication, network controls, and least-privilege permissions when remote access is required.

Should every Azure MCP tool be enabled?

No. Enable only the namespaces and tools needed by the client, and prefer read-only operation for discovery tasks.

Is Azure Container Apps required for Docker?

No. Container Apps is Microsoft’s remote hosting option. A local Docker workflow is a separate developer setup.

Where do I find the exact image tag?

Use the current official Azure MCP Server repository or Microsoft release documentation. Image tags and startup arguments can change, and the retrieved reference material does not specify a permanent tag.