Azure MCP in Claude Code

Quick answer: Install the Azure MCP server with npx -y @azure/mcp-server, add the JSON block below to ~/.claude/settings.json, restart Claude Code, and run /mcp to confirm the connection. Setup runs about 5 minutes on a fresh machine, verified against @azure/mcp-server as of April 15, 2026.

The Azure MCP server wraps Azure cloud resources into a tool surface Claude Code can call directly. After setup, the model can reach Azure cloud resources without you switching out of the editor. The server is published as @azure/mcp-server and talks to Claude Code over MCP on stdio.

This guide covers what you gain when the wiring is done, the exact config, verification steps, prompt patterns that tend to work well, and the four issues that trip people up most often in the first week.

What you get when it is connected

Once the Azure server is attached, Claude Code can call its tools from inside any conversation. You do not invoke the tools by hand. When you ask Claude a question the model decides which tool to call and parses the response for you. For teams that work against Azure cloud resources daily, this replaces dozens of context switches per week with a single line in chat.

The server exposes read and write tools that map to the underlying API. Read calls return structured JSON the model parses directly; write calls return the new resource so Claude can link back to it in chat. There is no local cache. Every call round-trips to the upstream service, so expect 200 to 800 ms per tool call depending on region and payload size.

Prerequisites

Node 20 or later, a terminal, and an account with enough access to cover the tools you plan to call. You will need: AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET. Grab these from your account settings before editing the Claude config. Paste the values into your shell profile rather than the JSON file itself so the secrets never enter git history.

If you use a version manager like nvm or asdf for Node, confirm the version Claude Code inherits. Open a terminal, run node -v, and note the output. Claude Code uses the Node it sees on PATH at launch, so a shell profile that sets the right version is the reliable path.

Install via npx

Run the package once with npx to verify it starts cleanly:

npx -y @azure/mcp-server

The first run downloads the package (a few MB) and starts the server on stdio. The server does not print much on success - it waits for MCP protocol messages on stdin. Press Ctrl-C to stop it. The real setup happens through Claude Code in the next step.

If the install fails with a network error, your npm registry may be blocked. Set npm config set registry https://registry.npmjs.org and retry. Behind a corporate proxy, also set HTTP_PROXY and HTTPS_PROXY in your shell.

Add the config block to ~/.claude/settings.json

Open ~/.claude/settings.json in your editor. If the file does not exist yet, create it with {} as the starting content. Add an mcpServers object with an entry for this server:

{
  "mcpServers": {
    "azure": {
      "command": "npx",
      "args": ["-y", "@azure/mcp-server"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "your_subscription_id",
        "AZURE_TENANT_ID": "your_tenant_id",
        "AZURE_CLIENT_ID": "your_client_id",
        "AZURE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Save the file. If you already have other MCP servers defined, merge the new entry into the existing mcpServers object rather than replacing it.

Restart Claude Code fully (quit and reopen, not just close the window). The server is spawned lazily on the first tool call in a session, not at launch, but the config is read once per Claude Code start.

Verify the connection

Open a new Claude Code session and type /mcp at the prompt. You should see the server listed with a connected indicator. If it shows as failed, click into it for the stderr output - the error message usually points at the problem directly (bad credentials, wrong path, or missing Node).

Run a trivial first prompt to confirm round trips work. For a read-heavy server, ask for a list of whatever resource type it exposes. For a write server, ask for a describe on a known resource first, then try a safe write on a test resource. If that first prompt works, the wiring is done. From there you interact with the server through normal prompts in Claude Code.

Example prompts that work well

Here are five prompts that tend to get good responses once the server is attached:

• List every resource group and their region.
• Describe a virtual machine and its current status.
• Show storage account usage for a specific account.
• Pull the last 20 activity log entries for a subscription.
• List App Service plans and their pricing tier.

Claude will chain tool calls on its own when the prompt implies several steps. For a summarize-then-write flow the model will often call read tools first and a single write tool at the end. If a prompt keeps burning tool calls, narrow it: specify the resource ID, the time range, or the exact field you want rather than asking Claude to scan everything.

A useful habit is to start every new session with a specific resource in mind, then let Claude hold that context across the conversation. That way the model does not repeat lookups and you get faster turnaround on follow-up questions.

Environment variable security

The credentials live in AZURE_SUBSCRIPTION_ID, AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET. Generate them in your account console and scope them as tightly as the service allows. Never commit the value. Store the secret in a shell profile env var and reference the variable name in the Claude config, or use a helper like op read from the 1Password CLI.

A general rule across every MCP server: never paste secrets directly into settings.json that lives in a shared or git-tracked directory. Keep the actual values in your shell profile (~/.zshrc, ~/.bashrc, or a 1Password helper), export them at shell start, and reference the variable names from the Claude config. That way the secret stays on your machine and the config file is safe to share with teammates.

On macOS, terminals launched from Spotlight or from the Dock both inherit the shell profile. If you launch Claude Code from a GUI shortcut that does not go through a shell, env vars may not propagate - launch from a terminal instead.

Troubleshooting

Server shows as failed in /mcp. The most common cause is a typo in the config JSON or a missing env var. Open ~/.claude/settings.json, validate the JSON in any linter, and confirm the env values are set in the shell that launched Claude Code. Restart fully after fixing.

Tool calls return 401 or authentication errors. The credential is wrong, expired, or scoped to the wrong account. Rotate AZURE_SUBSCRIPTION_ID in your account console, paste the new value into the env variable, and restart Claude Code. Tokens scoped to read only will fail on write operations with a similar error.

Tool calls hang for 30 seconds then fail. A network path between your machine and the Azure API is blocked. Try the same call from curl outside Claude Code to confirm. Behind a firewall, whitelist the API host or set HTTP_PROXY in the shell before launch.

Server spawns but no tools appear. The package may be outdated or the install is cached in a broken state. Run npx clear-npx-cache (or delete ~/.npm/_npx) and try again. For pinned versions, change the package reference to a newer release in the args array of the config.

For any issue not listed here, the first step is /mcp inside Claude Code to see the current status and any recent stderr from the server. The second step is running the exact npx command from your terminal to see if the server starts cleanly outside Claude Code. Between those two checks, most problems become obvious within a minute.

Next steps

Once the Azure server is attached and verified, the useful next move is writing a short prompt template you keep in your notes. List the three or four prompts you run most often against this server and paste them into Claude Code when needed. Over a few weeks you build a personal command library that gets real work done without typing much.

For team projects, commit a .mcp.json at the repo root with the same structure. Everyone on the team gets the server wired up automatically on first open, and individual secrets stay in shell profiles. That is the setup pattern that scales past a single developer.