Azure Cloud

Azure Cloud

Use the unified MCP server as a guarded Azure REST, realtime WebSocket, MQTT, and AMQP 1.0-over-WebSocket gateway. It obtains tokens only from non-CLI Azure Identity credentials: Service Principal environment, Workload Identity, or Managed Identity. There is no az rest or Azure CLI credential fallback.

Workflow

1. Call cloud_provider_status with provider="azure"; treat available as adapter readiness and credential_status=unverified as pending live authentication.
2. Verify the resource-provider API version in the official reference. azure_api_discover explains the adapter but cannot choose an API version for you.
3. Use azure_api_read for REST GET, HEAD, or OPTIONS. ACR data-plane reads use auth_scheme="acr", service="acr", and an exact acr_scope; the server performs both OAuth2 exchanges internally. Azure OpenAI auth_scheme="realtime-ws" uses the fixed read-only operations RealtimeResponse, RealtimeTranscription, or RealtimeSession; Chat Completions streaming uses auth_scheme="openai-chat-stream" with the read-only operation StreamChatCompletions; Responses streaming uses auth_scheme="openai-responses-stream" with the read-only operation StreamResponses. Voice Live auth_scheme="voice-live-ws" uses VoiceLiveResponse, VoiceLiveTranscription, or VoiceLiveSession; Foundry Agent mode is VoiceLiveAgentSession through azure_api_mutate with force=true.
4. Azure Web PubSub auth_scheme="webpubsub-ws" always uses azure_api_mutate(force=true). Web PubSub MQTT webpubsub-mqtt-ws and Event Grid MQTT v5 eventgrid-mqtt-ws use azure_api_read only for SubscribeMQTT; publishing or stateful ClientMQTT uses azure_api_mutate(force=true). Event Grid receives the Entra JWT only inside MQTT v5 CONNECT/AUTH. Azure SignalR Service auth_scheme="signalr-ws" uses azure_api_read only for Subscribe; hub Invoke calls use azure_api_mutate(force=true).
5. Service Bus servicebus-amqp-ws allows only PeekMessages through the read tool; send, schedule/cancel, receive/settlement, deferred, and session-state operations use mutation. Event Hubs eventhubs-amqp-ws uses read for properties/partition receive and mutation for send. Both use exact $servicebus/websocket, internal Entra/CBS, finite plans, and atomic output.
6. For POST, PUT, PATCH, or DELETE, obtain explicit human approval for the tenant/subscription, target URL, method, body, and effect; then use azure_api_mutate(force=true).
7. Secret-resource operations require the separate sensitive gate. Credential issuance/export endpoints such as Graph addPassword and resource listKeys are never exposed by the gateway.
8. Do not place bearer tokens, SAS signatures, client secrets, cookies, or API keys in URL/query/header arguments.

MCP arguments

• method and url: exact documented Azure REST request. Hosts are restricted to official Azure/Microsoft domains.
• subscription: optional audit and routing context; include the subscription in the documented URL when the API requires it.
• audience: optional Microsoft Entra resource/application audience for an uncommon official data-plane endpoint. Supply the documented audience, not a token; the server derives the .default scope internally.
• auth_scheme="acr": public Azure Container Registry data-plane HTTPS. Use service="acr", an exact <registry>.azurecr.io or documented regional login URL, and a path/method-matched acr_scope. Registry scopes are registry:catalog:* for catalog or /v2/ checks and registry:deleted_catalog:* for the deleted catalog. /v2/<repo>/... uses repository:<repo>:pull for GET/HEAD, push or the documented pull,push combination for POST/PUT/PATCH, and delete for DELETE. /acr/v1/<repo>/... uses metadata_read for GET/HEAD, metadata_write,metadata_read for PATCH, and delete for DELETE. Deleted lists use deleted_read; manifest restore uses deleted_read,deleted_restore. The repository in scope must exactly match the request path. A cross-repository blob mount additionally requires acr_source_scope="repository:<from>:pull", exact string from and mount parameters, and sends both scopes only to the internal token exchange. The server obtains the Entra ACR audience, exchanges it for an internal ACR refresh token and then a scoped access token, and exposes neither. Private Endpoint callers keep the public registry name and rely on VNet DNS. Read-only 307 redirects are followed only to the same registry's dedicated data endpoint or an Azure Blob host, with Authorization stripped; signed redirect URLs remain internal.
• headers: non-credential headers such as If-Match.
• body: JSON-compatible request body.
• body_file: binary/media request body under an operator-approved CLOUD_SKILLS_ALLOWED_FILE_ROOTS directory. Do not combine it with body; use provider multipart/chunk APIs above 64 MiB.
• response_file: new approved-root file for blob, export, backup, or other large responses. Use the official Range/x-ms-range header above the configured per-call limit; existing files are never overwritten.
• auth_scheme="realtime-ws": direct Azure OpenAI Realtime WSS using an internally acquired Microsoft Entra token for https://ai.azure.com/.default. Use service="openai", method="GET", the exact current public-cloud single-label host <resource>.openai.azure.com, and either a GA /openai/v1/realtime URL with exactly model=<deployment> or intent=transcription, or a preview /openai/realtime URL with api-version and deployment. Sovereign guesses, nested subdomains, direct private-DNS-zone hosts, and lookalikes are rejected. A normal public resource hostname may still resolve through Azure Private Link inside the operator VNet. Never supply handshake headers, API keys, bearer tokens, or an audience override.
• auth_scheme="voice-live-ws": public-cloud Azure Voice Live WSS through the non-CLI Azure Identity chain. Use service="voice-live", method="GET", exact path /voice-live/realtime, and a query-free single-label URL under <resource>.services.ai.azure.com or legacy <resource>.cognitiveservices.azure.com. Put api-version plus exactly model, or the agent_id/project_id pair, in parameters; Agent mode is mutation-only because the configured agent can invoke external tools. The server selects the official https://ai.azure.com/.default or legacy https://cognitiveservices.azure.com/.default scope from the endpoint and keeps the Bearer token inside the Upgrade. Sovereign, nested, direct private-DNS-zone, custom, and lookalike hosts are rejected before token resolution; normal public resource hostnames remain compatible with private DNS resolution inside the operator VNet.
• auth_scheme="openai-chat-stream": Azure OpenAI Chat Completions text/event-stream through the non-CLI Azure Identity chain. Use service="openai", method="POST", operation StreamChatCompletions, a date-structured api_version such as 2024-06-01, and the exact public-cloud https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions URL. body is a finite plan: model (must equal the deployment in the URL), 1–128 bounded messages with system|user|assistant|developer roles and string or {"type":"text","text":...} part content, optional max_tokens (1–1000000) and temperature (0–2), plus max_events (1–256) and timeout_seconds (1–300). The server requests https://cognitiveservices.azure.com/.default, forces "stream": true internally, sends the Bearer token only in the internal Authorization header, and rejects caller query parameters, headers, api-key/stream fields, and sovereign/nested/private-DNS-zone/lookalike hosts before token resolution. Each chat.completion.chunk is validated against the documented shape (id/object/created/model/choices/delta/finish_reason); unknown events, credential-bearing chunks, a missing data: [DONE] sentinel, or an empty stream fail atomically, and response_file receives sanitized chunk NDJSON only after the finite bound.
• auth_scheme="openai-responses-stream": Azure OpenAI Responses API text/event-stream through the non-CLI Azure Identity chain. Use service="openai", method="POST", operation StreamResponses, the exact public-cloud https://<resource>.openai.azure.com/openai/v1/responses URL, and an optional api_version of v1, preview, a date-structured version, or omitted for the v1 GA default. body is a finite plan: model (one bounded deployment name), input (a 1–65536-byte string or 1–64 message items with user|system|developer|assistant roles and string or {"type":"input_text","text":...} part content), optional max_output_tokens (1–1000000) and temperature (0–2), plus max_events (1–256) and timeout_seconds (1–300). The server requests https://cognitiveservices.azure.com/.default, forces "stream": true and "store": false internally so no response state is retained, sends the Bearer token only in the internal Authorization header, and rejects caller query parameters, headers, api-key/stream/store fields, and sovereign/nested/private-DNS-zone/lookalike hosts before token resolution. Each event is validated against the documented ResponseStreamEvent envelope (type allowlist plus sequence_number and per-type bounds); unknown or credential-bearing events, an error/response.failed termination, a stream that ends before response.completed/response.incomplete, or an empty stream fail atomically, and response_file receives sanitized event NDJSON only after the finite bound. The deprecated Assistants API (retired 2026-08-26) is not exposed; this Responses route is its documented replacement surface.
• For Realtime, body is one official client event or an array of events. For larger audio streams, use body_file as bounded NDJSON with one complete event per line, including official base64 input_audio_buffer.append events and commit events. response_file is required and receives validated server events as NDJSON only after all response.create/response.done and audio commit/transcription-completed pairs reach a successful terminal state. stream_interval_ms optionally paces outbound events.
• auth_scheme="webpubsub-ws": use service webpubsub, operation ClientConnect, method GET, and the exact public-cloud wss://<resource>.webpubsub.azure.com/client/hubs/<hub> URL. Private endpoints use that unchanged public resource URL and VNet DNS; never substitute a privatelink subdomain URL. body contains optional protocol="json|json-reliable|protobuf|protobuf-reliable" (default json), bounded user_id, documented roles and initial groups, 1–256 official logical messages, max_messages, and timeout_seconds (1–300). Protobuf mode converts those JSON-shaped messages to/from official proto3 binary frames and supports join/leave, publish, event, ping, stream start/data/end, text/binary/Any payloads, and every documented downstream message. Use {typeUrl,value} with Base64 value for Protobuf Any. Reliable mode requires an ackId on join/leave/publish/event requests, acknowledges exact uint64 sequences, drops duplicates, retries recovery for at most one minute, and resends only unacknowledged publisher messages; ping and stream control use their dedicated acknowledgements. response_file is required. Caller headers, query/recovery parameters, access tokens, client-token/reconnection-token responses, custom endpoints, and body files are forbidden.
• auth_scheme="signalr-ws": Azure SignalR Service serverless JSON-hub WSS through the non-CLI Azure Identity chain. Use service signalr, method GET, and the exact public-cloud wss://<resource>.service.signalr.net/client/?hub=<hub> URL. body is a finite plan: optional bounded user_id, optional minutes_to_expire (1–60, default 5), max_messages, and timeout_seconds (1–300). Subscribe is read-only and accepts no invocations: the gateway connects, performs the official {"protocol":"json","version":1} handshake, collects server-to-client Invocation frames, and auto-replies with void Completion frames so pending server invocations do not stall. Invoke is mutation-only and requires 1–64 bounded invocations, each with a unique id, a bounded target, and at most 32 credential-free arguments; the gateway sends the official type-1 Invocation frames, correlates StreamItem/Completion responses by id, fails on error Completions or missing terminal Completions, and never accepts caller headers or query parameters. The server requests https://signalr.azure.com/.default, calls the fixed POST /api/hubs/<hub>/:generateToken data-plane API (official api-version=2022-11-01), and passes the client token only in the internal access_token query parameter of the dial URL; Entra token, client token, and handshake frames never enter MCP output. response_file is required and receives sanitized protocol JSON as atomic NDJSON.
• auth_scheme="webpubsub-mqtt-ws": use service webpubsub, method GET, and exact wss://<resource>.webpubsub.azure.com/clients/mqtt/hubs/<hub>; the same public-name/private-DNS rule applies to private endpoints. protocol_version is 4 (MQTT 3.1.1, default) or 5; client_id is 1–128 ASCII alphanumeric bytes; topics are exact and bounded; keep_alive_seconds, max_messages, and timeout_seconds keep every session finite. SubscribeMQTT is read-only and requires 1–8 subscriptions at QoS 0/1/2, clean start, and no publish/Will/session persistence. ClientMQTT is mutation-only and accepts up to eight subscriptions plus eight initial Base64 publishes, QoS 0/1/2, optional Last Will, and max_messages=0 for publish-only calls. MQTT 5 additionally accepts session expiry up to 30 seconds, subscription identifier, payload format/content type/message expiry, and Will delay. The gateway implements both QoS 2 directions exactly once, honors broker Receive Maximum/Maximum Packet Size/Maximum QoS/Server Keep Alive, derives exact join/send roles, and writes Base64 NDJSON atomically. Retained messages, wildcard/shared subscriptions, and topic alias are rejected because Azure does not support them. Username/password, caller tokens, and client certificates are excluded by the operator-IAM-only credential boundary.
• auth_scheme="eventgrid-mqtt-ws": use service eventgrid, MQTT v5 only, method GET, and exact wss://<namespace>.<region>.eventgrid.azure.net/mqtt or an operator-pinned custom domain. SubscribeMQTT is read-only; ClientMQTT is mutation-only. The finite body supports QoS 0/1 subscriptions and Base64 publishes, wildcard/shared filters, session expiry up to eight hours, retained/Last Will, user properties, response topic/correlation data, message expiry, topic aliases up to 10, subscription identifiers, assigned client IDs, receive/packet flow control, keepalive up to 1160 seconds, and optional reauthenticate_after_seconds. The server requests https://eventgrid.azure.net/.default, puts OAUTH2-JWT and the JWT only in CONNECT/AUTH, enforces the 512 KiB broker packet limit, and writes output atomically.
• auth_scheme="servicebus-amqp-ws": use service servicebus, method GET, and exact wss://<namespace>.<servicebus-suffix>/$servicebus/websocket. The only accepted active-cloud suffixes are servicebus.windows.net, servicebus.usgovcloudapi.net, and servicebus.chinacloudapi.cn. Private-link aliases, custom/lookalike hosts, and retired Germany endpoints are rejected. Supported broker operations are PeekMessages, SendMessages, ScheduleMessages, CancelScheduledMessages, ReceiveMessages, ReceiveDeferredMessages, GetSessionState, and SetSessionState. Plans select a queue, or a topic plus subscription for receiver operations. Message bodies and session state are canonical Base64; common broker/application properties, dead-letter and subqueue semantics are supported. Receive requires an explicit in-call settlement and never returns the lock token. Session ID or accept-next is bounded to the invocation; session locks are never exported.
• auth_scheme="eventhubs-amqp-ws": use service eventhubs, method GET, and the same exact three active-cloud namespace WSS endpoint forms. GetProperties returns hub and optional partition properties; ReceiveEvents reads one partition from exactly one bounded start position with max count/timeout/prefetch; SendEvents sends a finite batch with optional partition ID or partition key. Epoch/owner capability and checkpoint-store credentials are not caller fields. The server uses the official Azure Go SDK AMQP engine and internal Entra/CBS token refresh for both messaging services.

Example read: azure_api_read(method="GET", url="https://management.azure.com/subscriptions/<id>/resources?api-version=2021-04-01", subscription="<id>").

Example ACR tags read: azure_api_read(auth_scheme="acr", service="acr", operation="ListTags", method="GET", url="https://<registry>.azurecr.io/v2/<repository>/tags/list", parameters={"n":100}, acr_scope="repository:<repository>:pull").

Example Realtime text response: azure_api_read(auth_scheme="realtime-ws", service="openai", operation="RealtimeResponse", method="GET", url="wss://<resource>.openai.azure.com/openai/v1/realtime", parameters={"model":"<deployment>"}, body=[{"type":"conversation.item.create","item":{"type":"message","role":"user","content":[{"type":"input_text","text":"Please assist the user."}]}},{"type":"response.create"}], response_file="/approved/results/realtime.ndjson").

Example Voice Live response: azure_api_read(auth_scheme="voice-live-ws", service="voice-live", operation="VoiceLiveResponse", method="GET", url="wss://<resource>.services.ai.azure.com/voice-live/realtime", parameters={"api-version":"2026-04-10","model":"gpt-realtime"}, body=[{"type":"session.update","session":{"voice":{"name":"en-US-AvaNeural","type":"azure-standard"},"modalities":["text","audio"]}},{"type":"response.create"}], response_file="/approved/results/voice-live.ndjson"). A response operation must contain response.create, transcription must contain input_audio_buffer.commit, and a session-only call must contain session.update; this gives each WSS call an observable finite terminal condition. Voice Live avatar WebRTC is not exposed: server-returned ICE credentials are rejected before atomic output.

Example Chat Completions stream: azure_api_read(auth_scheme="openai-chat-stream", service="openai", operation="StreamChatCompletions", method="POST", url="https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions", api_version="2024-06-01", body={"model":"<deployment>","messages":[{"role":"user","content":"Summarize cloud skills in one sentence."}],"max_events":32,"timeout_seconds":30}, response_file="/approved/results/chat-stream.ndjson"). The gateway injects "stream": true, validates every chat.completion.chunk, and writes sanitized NDJSON only after the bounded event count, the [DONE] sentinel, or the finite timeout.

Example Responses stream: azure_api_read(auth_scheme="openai-responses-stream", service="openai", operation="StreamResponses", method="POST", url="https://<resource>.openai.azure.com/openai/v1/responses", api_version="v1", body={"model":"<deployment>","input":"Summarize cloud skills in one sentence.","max_events":32,"timeout_seconds":30}, response_file="/approved/results/responses-stream.ndjson"). The gateway injects "stream": true and "store": false, validates every ResponseStreamEvent, and writes sanitized NDJSON only after the bounded event count, response.completed/response.incomplete, or the finite timeout.

Example Web PubSub subscription: azure_api_mutate(auth_scheme="webpubsub-ws", service="webpubsub", operation="ClientConnect", method="GET", url="wss://<resource>.webpubsub.azure.com/client/hubs/<hub>", body={"roles":["webpubsub.joinLeaveGroup.<group>"],"groups":["<group>"],"messages":[{"type":"joinGroup","group":"<group>","ackId":1}],"max_messages":32,"timeout_seconds":30}, response_file="/approved/results/webpubsub.ndjson", force=true). The gateway uses Entra to call the fixed Generate Client Token API, keeps both tokens internal, requires json.webpubsub.azure.v1, rejects failed acknowledgements, and atomically publishes only bounded protocol JSON.

Example SignalR subscribe: azure_api_read(auth_scheme="signalr-ws", service="signalr", operation="Subscribe", method="GET", url="wss://<resource>.service.signalr.net/client/?hub=chat_hub", body={"user_id":"observer","max_messages":32,"timeout_seconds":30}, response_file="/approved/results/signalr-subscribe.ndjson"). The gateway obtains https://signalr.azure.com/.default, mints the five-minute client token through :generateToken, connects with the token only in access_token, completes the JSON-hub handshake, and atomically writes each server-to-client Invocation as sanitized NDJSON.

Example SignalR invoke: azure_api_mutate(auth_scheme="signalr-ws", service="signalr", operation="Invoke", method="GET", url="wss://<resource>.service.signalr.net/client/?hub=chat_hub", body={"invocations":[{"id":"inv-1","target":"SendMessage","arguments":[{"text":"hello"}]}],"max_messages":4,"timeout_seconds":30}, response_file="/approved/results/signalr-invoke.ndjson", force=true). StreamItem/Completion frames are correlated to the invocation IDs and atomically published only after every invocation completes without an error Completion.

For reliable delivery, add protocol="json-reliable" to that body. The gateway requires json.reliable.webpubsub.azure.v1, removes the reconnection token before output, automatically emits sequenceAck, suppresses redelivered sequence IDs, and performs bounded recovery without exposing its internal recovery URL.

For binary Protobuf delivery, use protocol="protobuf" or protocol="protobuf-reliable". Example: azure_api_mutate(auth_scheme="webpubsub-ws", service="webpubsub", operation="ClientConnect", method="GET", url="wss://<resource>.webpubsub.azure.com/client/hubs/<hub>", body={"protocol":"protobuf-reliable","roles":["webpubsub.sendToGroup.<group>"],"messages":[{"type":"sendToGroup","group":"<group>","ackId":1,"dataType":"protobuf","data":{"typeUrl":"type.googleapis.com/example.Message","value":"CAE="}}],"max_messages":32,"timeout_seconds":30}, response_file="/approved/results/webpubsub-protobuf.ndjson", force=true). The gateway requires the exact reliable Protobuf subprotocol, uses only binary WebSocket frames, and returns sanitized logical NDJSON instead of raw protobuf or recovery tokens.

Example MQTT 5 read: azure_api_read(auth_scheme="webpubsub-mqtt-ws", service="webpubsub", operation="SubscribeMQTT", method="GET", url="wss://<resource>.webpubsub.azure.com/clients/mqtt/hubs/<hub>", body={"protocol_version":5,"client_id":"Observer123","subscriptions":[{"topic_filter":"room/in","qos":2}],"subscription_identifier":7,"keep_alive_seconds":30,"max_messages":32,"timeout_seconds":30}, response_file="/approved/results/mqtt.ndjson").

Example MQTT 5 publish: azure_api_mutate(auth_scheme="webpubsub-mqtt-ws", service="webpubsub", operation="ClientMQTT", method="GET", url="wss://<resource>.webpubsub.azure.com/clients/mqtt/hubs/<hub>", body={"protocol_version":5,"client_id":"Publisher123","publishes":[{"topic":"room/out","qos":2,"payload_base64":"aGVsbG8=","payload_format":1,"content_type":"text/plain"}],"keep_alive_seconds":30,"max_messages":0,"timeout_seconds":30}, response_file="/approved/results/mqtt-publish.ndjson", force=true).

Example Event Grid MQTT v5 read: azure_api_read(auth_scheme="eventgrid-mqtt-ws", service="eventgrid", operation="SubscribeMQTT", method="GET", url="wss://<namespace>.<region>.eventgrid.azure.net/mqtt", body={"client_id":"observer-1","username":"workload-app","subscriptions":[{"topic_filter":"$share/processors/orders/+","qos":1}],"subscription_identifier":7,"keep_alive_seconds":30,"max_messages":32,"timeout_seconds":30}, response_file="/approved/results/eventgrid-mqtt.ndjson").

Example Service Bus peek: azure_api_read(auth_scheme="servicebus-amqp-ws", service="servicebus", operation="PeekMessages", method="GET", url="wss://<namespace>.servicebus.windows.net/$servicebus/websocket", body={"queue":"orders","max_messages":25,"timeout_seconds":30}, response_file="/approved/results/servicebus.ndjson").

Example Event Hubs receive: azure_api_read(auth_scheme="eventhubs-amqp-ws", service="eventhubs", operation="ReceiveEvents", method="GET", url="wss://<namespace>.servicebus.windows.net/$servicebus/websocket", body={"event_hub":"telemetry","consumer_group":"$Default","partition_id":"0","start_position":{"earliest":true},"max_events":25,"timeout_seconds":30,"prefetch":25}, response_file="/approved/results/eventhubs.ndjson").

Common ARM, Graph, Storage, Key Vault, SQL, Service Bus, Monitor, App Configuration, Search, Databricks, Grafana, Web PubSub, SignalR, Digital Twins, Synapse, Log Analytics, ACR, Azure Maps, FHIR, and DICOM endpoints have built-in audience routing. Azure Maps callers must include the documented non-secret x-ms-client-id header. FHIR uses its service URL as the default audience; DICOM uses https://dicom.healthcareapis.azure.com. Use an explicit documented audience when a FHIR deployment overrides its default authentication audience.

Configure the matching Azure authority in Azure Identity before calling a sovereign endpoint. AMQP messaging accepts public Azure, Azure US Government, and Azure operated by 21Vianet; the retired Microsoft Cloud Germany endpoint is intentionally excluded. Azure OpenAI Realtime and Chat Completions streaming remain public-cloud only: the current contracts publish the .openai.azure.com endpoint and public Global deployment regions, while the Azure Government model page states that its list includes all Azure OpenAI models offered there and lists no Realtime model; Azure China has no published Foundry Realtime endpoint contract. Voice Live is also public-cloud only because the current Azure Speech sovereign-cloud table explicitly lists it as unsupported in both Azure Government and Azure operated by 21Vianet. Web PubSub remains public-cloud only because Azure Government does not list it as GA and no current China data-plane endpoint contract is documented. Azure SignalR Service remains public-cloud only in this adapter: the current English documentation publishes the https://signalr.azure.com/.default scope and <resource>.service.signalr.net client endpoint, and the adapter rejects sovereign host guesses and lookalikes before token resolution. Event Grid Namespace MQTT remains public-cloud only until Microsoft documents that MQTT namespace subfeature and endpoint for a sovereign cloud.

Credentials

Authenticate the server process through managed identity, workload identity, or an Azure service principal (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET). Managed Identity is always the final non-CLI source in the lazy Azure Identity chain, so Azure-hosted workloads do not need a cloud CLI or an extra activation flag. Credentials stay in Azure Identity and are never MCP parameters.

Read references/official-docs.md before selecting authentication or an API version.