Azure Connector Namespace (generic)

Manage Microsoft.Web connector namespaces, their connections, trigger configs, and MCP server configs. This skill is sandbox-agnostic — it does not assume your callback target. Callbacks can be any HTTP(S) URL (Function App, Logic App, App Service, ngrok, anywhere) and you choose how the namespace authenticates to it.

If you specifically need to fan events into an Azure Container Apps sandbox group (with declarative gatewayConnections[] wiring and sandbox callbacks), use the companion skill at plugin/skills/aca-sandboxes instead.

Naming note. This skill was previously called "Connector Gateway". The resource is now displayed as "Connector Namespace" everywhere (matching the portal rename). The ARM resource type is still Microsoft.Web/connectorGateways (legacy URL segment kept for backwards compatibility) and the property gatewayConnections[] on sandbox groups also keeps its name. Do not rewrite those API strings.

Three patterns this skill supports

Rules (MUST follow)

When to STOP and ask the user: subscription/resource group, namespace name, connection name, any parameter with dynamic values (teams/channels/folders/sites/lists), callback URL, callback authentication type, MSI audience (if MSI auth chosen — default to https://management.azure.com/ if user doesn't provide one), OAuth consent completion, MCP per-parameter triage (userParameter vs agentParameter vs skip — for every path/query/body field, including each body sub-property).

When to EXECUTE immediately: namespace/connection/trigger/MCP-config/access-policy CRUD, role assignments, dynamic-value lookups.

Step 0: Prerequisites & Azure context

1. Check az account show. If missing, see prerequisites.md.
2. Select subscription — list, ask user to pick:

   az account list --query "[].{name:name, id:id, isDefault:isDefault}" -o table
   

   Set if non-default: az account set --subscription "{sub}". Store {sub} for all subsequent commands.
3. Select resource group:
   • Existing: az group list --query "[].{name:name, location:location}" -o table → user picks.
   • New: ask for name + location, then az group create --name {rg} --location {location}.

Stop and wait for the user's answers before continuing.

Step 1: Namespace setup

ARM base: https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGatewaysAPI version: 2026-05-01-preview

Ask the user: "Do you have an existing connector namespace, or should I create a new one?"

• Existing: ask for the name and fetch it:

  az rest --method GET \
    --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGateways/{namespace}?api-version=2026-05-01-preview" \
    --query "{name:name, location:location, principalId:identity.principalId, tenantId:identity.tenantId, identityType:identity.type, userAssigned:identity.userAssignedIdentities}"
  

• New: ask for {namespace} name + location. Create with a SystemAssigned managed identity (required for trigger event subscriptions on connector-event triggers AND for ManagedServiceIdentity callback auth):

  $namespaceBody = @{ location = "{location}"; identity = @{ type = "SystemAssigned" } } | ConvertTo-Json -Compress
  $tmp = New-TemporaryFile; Set-Content $tmp $namespaceBody
  az rest --method PUT `
    --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGateways/{namespace}?api-version=2026-05-01-preview" `
    --body "@$tmp" `
    --query "{name:name, principalId:identity.principalId, tenantId:identity.tenantId}"
  Remove-Item $tmp
  

Capture principalId and tenantId — needed later for the namespace-acl access policy and (optionally) for ManagedServiceIdentity callback authentication.

If a user later wants to call their callback URL using a user-assigned identity, they'll need to add that identity to the namespace separately. See notification-authentication.md.

Step 2: Connection(s) + OAuth consent

Required for trigger configs, MCP server configs, and direct API calls. Recurrence / sliding-window triggers with no connector-event source can skip this.

Create connections in parallel:

$connBody = @{ properties = @{ connectorName = "office365" }; location = "{location}" } | ConvertTo-Json -Compress
$tmp = New-TemporaryFile; Set-Content $tmp $connBody
az rest --method PUT `
  --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGateways/{namespace}/connections/o365-conn?api-version=2026-05-01-preview" `
  --body "@$tmp"
Remove-Item $tmp

Then generate consent links and open in the browser — see consent.md for the exact body format and Start-Process pattern. Verify status Connected before continuing. See also connections.md for the full CRUD reference.

For trigger configs: also create a namespace-acl access policy granting the namespace MI access to the connection (required for the namespace to subscribe to connector events). See trigger-setup.md Step 4.

Step 3: Choose the pattern

Ask the user:

• A) Trigger config — push notifications to your callback URL when events happen, or on a schedule.
• B) MCP server config — expose selected connector operations as MCP tools at a namespace endpoint, callable by any MCP client (Claude Desktop, VS Code, etc.).
• C) Direct API call — one-off dynamicInvoke (send an email now, list items now).

Stop and wait for the user's answer.

• A → Step 4A
• B → Step 4B
• C → Step 4C

Step 4A: Trigger config

→ Full details: trigger-setup.md | Auth options: notification-authentication.md | Dynamic params: dynamic-values.md

1. Pick the trigger source. Ask the user:
   • Connector event (e.g., new email, new file, new form response) — needs the connection from Step 2.
   • Recurrence — fires every N seconds / minutes / hours / days.
   • Sliding window — fires on time intervals with startTime/endTime window state.
2. Connector event: discover trigger operations on the connector:

   az rest --method GET \
     --url "https://management.azure.com/subscriptions/{sub}/providers/Microsoft.Web/locations/{location}/managedApis/{connector}/apiOperations?api-version=2016-06-01" \
     --query "value[?properties.trigger != null].{name:name, summary:properties.summary, trigger:properties.trigger}" -o table
   

   
   Pick one with the user. Enumerate every parameter — including each sub-property of a body object (resolve $ref, recurse into nested objects and array items). Triage each leaf:
   • x-ms-dynamic-* → resolve via dynamic-values.md. STOP at every dynamic param.
   • Static enum → present choices and STOP for user pick.
   • Free-form with obvious default (e.g., folderPath=Inbox) → use default, inform user.
   • Free-form with no default → STOP and ask the user.
   
   When assembling parameters[], build a nested object — do NOT emit dotted leaf names. All body-sourced leaves (top-level body + every nested sub-property) collapse into ONE entry whose name is literally the string "body" (NOT the Swagger body parameter's name) and whose value is the nested object. Non-body dotted leaves group under their root segment. See trigger-setup.md §2b for the exact pattern and worked examples.
3. Recurrence / sliding window: ask for frequency (Second/Minute/Hour/Day) and interval.
4. Callback URL — ask the user explicitly. Do NOT invent one. Format examples:
   • Function App: https://{app}.azurewebsites.net/api/{fn}?code={key}
   • Logic App HTTP trigger: full SAS URL from the Logic App's "When a HTTP request is received"
   • Custom API: any https://... endpoint
5. Callback authentication — ask the user. Options (full reference in notification-authentication.md):

   Type	Use when
   (none)	Callback URL already contains its own auth token (e.g., Logic App SAS in querystring)
   QueryString	Add a ?key=value automatically (e.g., Function App key)
   Raw	Send a literal Authorization: <scheme> <parameter> header
   Basic	HTTP Basic with username/password
   ManagedServiceIdentity	Namespace acquires a token for audience using its own MI (system- or user-assigned). Ask the user for audience — if they don't provide one, default to https://management.azure.com/. Never use the callback URL as the audience. See notification-authentication.md.
   ActiveDirectoryOAuth	Namespace authenticates as an Entra app (tenant/clientId/secret/audience)
   ClientCertificate	Mutual TLS with a pfx/password

6. Create the trigger config (one PUT). See trigger-setup.md Step 3 for the canonical body templates for each source × auth combination.
7. Create the namespace-acl (only for connector-event triggers). See trigger-setup.md Step 4.
8. Verify the trigger state is Enabled:

   az rest --method GET \
     --url "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGateways/{namespace}/triggerConfigs/{name}?api-version=2026-05-01-preview" \
     --query "properties.state" -o tsv
   

Step 4B: MCP server config

→ Full details: mcp-server-config.md | Dynamic params: dynamic-values.md

1. Pick connector(s) + operation(s). Discover them:

   az rest --method GET \
     --url "https://management.azure.com/subscriptions/{sub}/providers/Microsoft.Web/locations/{location}/managedApis/{connector}/apiOperations?api-version=2016-06-01" \
     --query "value[?properties.trigger == null].{name:name, summary:properties.summary, description:properties.description}" -o table
   

   
   Each MCP "tool" maps to one connector operation under one connection.
2. For each operation, triage every parameter — including each body sub-property.
   First enumerate every parameter from the Swagger:
   • All parameters[] entries (path / query / body / header).
   • For each body parameter whose schema is an object (resolve $ref), enumerate its properties and the inner required array. Recurse into nested objects and items of arrays.
   
   Then resolve dynamic markers — the four extension kinds (x-ms-dynamic-values, -list, -tree, -schema) all apply here, exactly like trigger setup:
   • x-ms-dynamic-values / -list → dynamicInvoke the lookup operation, STOP for user pick, store the value-path value.
   • x-ms-dynamic-tree → walk the tree (root → children), STOP at each level, store the final opaque token.
   • x-ms-dynamic-schema / -properties → resolve schema after parents are picked. Bake the parents so the LLM gets a stable tool shape.
   • Cascading params (e.g., channel depends on team): always resolve parents first; pass their value (not display name) to child lookups.
   
   STOP and ask the user, for every parameter (and every required body sub-property), whether it should be:

   Choice	What it means
   userParameter	Bake a fixed value now ({name, value}). LLM cannot change it. Use this for enumerable connector IDs (team/channel/site/list/folder/file/db/table) and for org-default fields.
   agentParameter	LLM supplies on each call ({name, schema}). Use this for free-form content (subject/body/recipient) and for required fields with no fixed value.
   skip	Only valid if the field is optional (not in the Swagger required array).

   
   Required fields cannot be skipped. Body sub-properties are nested under one agentParameter whose schema.type is "object" and whose schema.properties mirrors the body. See mcp-server-config.md §"Per-parameter triage workflow" and dynamic-values.md.
3. PUT the MCP server config. Body shape:

   {
     "properties": {
       "description": "...",
       "connectors": [
         {
           "name": "office365",
           "displayName": "Office 365",
           "connectionName": "o365-conn",
           "operations": [
             {
               "name": "Send_Email_(V2)",
               "displayName": "Send Email",
               "description": "Send an email via Office 365.",
               "userParameters": [
                 { "name": "from", "value": "alerts@contoso.com" }
               ],
               "agentParameters": [
                 { "name": "emailMessage", "schema": { "type": "object", "required": true, "properties": { "To": { "type": "string", "required": true }, "Subject": { "type": "string" }, "Body": { "type": "string" } } } }
               ]
             }
           ]
         }
       ]
     }
   }
   

   
   PUT to: .../connectorGateways/{namespace}/mcpServerConfigs/{name}?api-version=2026-05-01-preview

   Always serialize with ConvertTo-Json -Depth 20 (or higher). The default depth (2) silently flattens nested body schemas to the literal string "System.Collections.Hashtable". GET the config after the PUT and verify the nested properties are real objects.

4. GET the config and return properties.mcpEndpointUrl — that's the URL the MCP client points at. See mcp-server-config.md for the auth-mode + access-policy details.

Step 4C: Direct API call via dynamicInvoke

→ Full details: direct-api.md | Dynamic params: dynamic-values.md

1. Get the connector Swagger (managedApis/{connector}?export=true) → operationId → path table
2. Resolve any x-ms-dynamic-* parameters with dynamic-values.md. STOP at every dynamic param.
3. POST to dynamicInvoke with the resolved method + path (+ optional queries, body, non-Content-* headers).

Final verification checklist

For trigger configs (path A):

• ✅ Namespace exists; for ManagedServiceIdentity callback auth, namespace has the requested identity
• ✅ For connector-event triggers: connection Connected, namespace-acl exists on the connection
• ✅ Trigger properties.state is Enabled
• ✅ User-provided callback URL is reachable + accepts the chosen auth

For MCP server configs (path B):

• ✅ All referenced connections are Connected
• ✅ properties.mcpEndpointUrl is populated in the GET response
• ✅ For Hosted MCP servers with AuthenticationMode != NotSpecified: resourceAuth is set (see mcp-server-config.md)
• ✅ Access policies on the MCP server config grant the consuming clients access

For direct API (path C):

• ✅ Connection Connected
• ✅ dynamicInvoke returns response.statusCode in 2xx

Quick reference

# ARM base:  https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorGateways
# API ver:   api-version=2026-05-01-preview

# Namespace
az rest --method GET --url ".../connectorGateways/{namespace}?api-version=2026-05-01-preview"

# Connections
az rest --method GET --url ".../connectorGateways/{namespace}/connections?api-version=2026-05-01-preview"

# List trigger operations + summaries
az rest --method GET --url ".../locations/{location}/managedApis/{connector}/apiOperations?api-version=2016-06-01"

# Get Swagger (paths, parameters, x-ms-dynamic-*)
az rest --method GET --url ".../locations/{location}/managedApis/{connector}" --url-parameters "api-version=2016-06-01" "export=true"

# Dynamic invoke
az rest --method POST --url ".../connectorGateways/{namespace}/connections/{conn}/dynamicInvoke?api-version=2026-05-01-preview" --body '{"request":{"method":"GET","path":"/..."}}'

# Trigger configs
az rest --method GET --url ".../connectorGateways/{namespace}/triggerConfigs?api-version=2026-05-01-preview"
az rest --method POST --url ".../connectorGateways/{namespace}/triggerConfigs/{name}/disable?api-version=2026-05-01-preview"
az rest --method POST --url ".../connectorGateways/{namespace}/triggerConfigs/{name}/enable?api-version=2026-05-01-preview"

# MCP server configs
az rest --method GET --url ".../connectorGateways/{namespace}/mcpServerConfigs?api-version=2026-05-01-preview"
az rest --method GET --url ".../connectorGateways/{namespace}/mcpServerConfigs/{name}?api-version=2026-05-01-preview" --query "properties.mcpEndpointUrl" -o tsv

References

• prerequisites.md — required tooling and Azure setup
• quickstart.md — minimal commands to list everything
• connections.md — connection CRUD + ACLs
• consent.md — OAuth consent link generation (exact body format)
• dynamic-values.md — x-ms-dynamic-{values,list,tree,schema} resolution algorithms
• trigger-setup.md — trigger config creation (all source types, all auth types)
• notification-authentication.md — callback authentication reference
• mcp-server-config.md — MCP server config CRUD
• direct-api.md — dynamicInvoke recipes
• trigger-flow.md — end-to-end architecture diagram
• tutorial.md — walkthrough: recurrence trigger → user webhook
• gotchas.md — common issues