mcp-azure-toolkit

An MCP server that exposes core Azure services as read-mostly tools any MCP client can call.

What it is - Install - Configure - Run and register with a client - Tools - Architecture - Security model - Design decisions - Development - Benchmarks - Known limitations - Contributing - License

What it is

mcp-azure-toolkit is a Model Context Protocol (MCP) server that lets an AI client - GitHub Copilot, Claude Desktop, Cursor - inspect Azure resources through a small, safe set of tools. It speaks MCP over stdio: an MCP client launches it as a subprocess, and the model calls its tools to list blob containers, read secrets by name, peek a Service Bus queue, enumerate resource groups, and so on.

Two things make it safe to hand to an autonomous client:

• It authenticates with DefaultAzureCredential, so it uses whatever identity the host already has (Azure CLI login, managed identity, environment credentials). There are no secrets in the server config.

• The exposed operations are read-mostly by design. Destructive operations are intentionally omitted (see Security model).

You only enable the services you configure: set just the storage variables and you get a blob-only server. The live Azure path has been verified end-to-end against a real storage account.

Install

pip install "mcp-azure-toolkit[azure]"

The [azure] extra pulls in the per-service Azure SDKs. The bare package (mcp and azure-identity only) installs without them, which is useful for development against the in-memory backends. Python 3.11+ is required.

Configure

Set the environment variables for the services you want to expose. Each is optional - a service is registered only when its variable is present.

Authentication uses DefaultAzureCredential: run az login, or supply a managed identity or environment credentials. No keys go in this config. See .env.example for a starting point.

Run and register with a client

Run it directly as a stdio MCP server (this is how a client launches it):

mcp-azure-toolkit

It is installed as a console-script entry point, so the command resolves to the server's stdio loop. Normally you do not run it by hand - you register the command with an MCP client. For example, Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "azure-toolkit": {
      "command": "mcp-azure-toolkit",
      "env": {
        "AZURE_STORAGE_ACCOUNT_URL": "https://acct.blob.core.windows.net",
        "AZURE_SUBSCRIPTION_ID": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}

The server is also published with a smithery.yaml so it can be discovered and launched through the Smithery MCP registry.

Tools

Nine tools across four services. Only the tools whose service you configured are registered.

Tools return plain JSON-serialisable values (strings, lists, dicts), so any MCP client can consume them.

Architecture

An MCP client launches the server over stdio. At startup the server reads config.py, and build_azure_server (server.py) registers tools for only the configured services. Each tool depends on a narrow async backend protocol, never on the Azure SDK directly:

• Server and tool registration. build_server takes any subset of backends and wires their operations up as MCP tools (tools.py). The same function is used in production and in tests.

• Backend protocols. BlobBackend, SecretsBackend, ServiceBusBackend, and ResourceBackend (backends.py) define the minimal surface each tool group needs.

• Two implementations per protocol. Azure*Backend wraps the real Azure SDK; the synchronous SDK clients run in a worker thread via asyncio.to_thread so they do not block the event loop. InMemory*Backend is a dependency-free fake.

• Four Azure services. Blob Storage, Key Vault, Service Bus, and Resource Manager, each reached through DefaultAzureCredential.

Because tools see only the protocols, the same server runs against real Azure or against the in-memory fakes with no code change. That is what lets the whole tool surface be tested with no live subscription.

Security model

• No secrets in config. Authentication is DefaultAzureCredential, so the server borrows the host's existing identity (az login, managed identity, or environment credentials). Nothing sensitive is stored in the MCP client config or the environment file beyond resource URLs.

• Read-mostly by design. The exposed operations are deliberately limited: blobs and secrets are read-only, and Service Bus offers send plus a non-destructive peek. Destructive operations (delete, purge, overwrite) are intentionally omitted so the server is safe to hand to an autonomous AI client. If you need them, add them behind an approval gate.

• Least surface by default. Only the services you explicitly configure are registered, so an unconfigured service is not reachable at all.

Design decisions

• Backend protocol plus fakes. Tools depend on small async protocols rather than the Azure SDK. This keeps the tool layer testable without Azure and makes the safety boundary (which operations exist) explicit and easy to audit.

• Sync SDK wrapped in asyncio.to_thread. The Azure SDK clients used here are synchronous; running them in a worker thread keeps the async MCP server responsive without pulling in the async SDK variants.

• Optional per-service registration. Configuration is all-optional and a service is only wired up when its variable is set, so the same package can be a blob-only server or a full four-service server.

• Azure SDKs behind an optional extra. The base install stays lean (just mcp and azure-identity); the heavier per-service SDKs come with [azure].

Development

The full tool surface is tested against the in-memory backends, so no Azure subscription or credentials are needed.

pip install -e ".[dev]"
pytest          # tool surface tested against in-memory backends, no Azure needed
ruff check .
mypy mcp_azure_toolkit

Benchmarks

The numbers below measure the toolkit's own dispatch overhead (argument validation, tool lookup, async invocation, result serialisation) using the in-memory backends, so they do not include any Azure round-trip. Regenerate with python scripts/benchmark.py | python scripts/inject_readme_section.py --section benchmarks.

In-memory tool-dispatch latency over 2000 iterations per tool (no live Azure; measures toolkit overhead only).

Known limitations

• Operations are read-mostly on purpose; there are no delete/purge/overwrite tools.

• Blob reads decode content as UTF-8 text, so binary blobs are not supported by blob_read.

• The real Azure*Backend classes require a live Azure subscription and are exercised only against one; they are excluded from coverage.

• The toolkit covers four services (Blob, Key Vault, Service Bus, Resource Manager); other Azure services are out of scope for now.

Contributing

Contributions are welcome. A good change adds or fixes a tool with a test that runs against an in-memory backend (no live Azure), keeps operations read-mostly by default, and follows the existing style. Open an issue describing the change before a large PR.

License

MIT