Add azure-connectornamespace skill#122
Closed
DevArjun23 wants to merge 11 commits into
Closed
Conversation
New skill under Skills/General/azure-connectorgateway providing a sandbox-agnostic playbook for managing Microsoft.Web connector gateways, connections, trigger configs, and MCP server configs. The customer-owned callback URL and notification authentication are user-provided; the skill never assumes a sandbox runtime. Trigger types covered: connector-event, Recurrence, SlidingWindow. MCP focus is on ManagedMcpServer; HostedMcpServer is referenced briefly. Reuses dynamic-values resolution and consent flow from the existing Skills/Sandbox/azure-connectorgateway skill. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Expand mcp-server-config.md with a full "Resolving dynamic parameters for MCP config" section that covers all four x-ms-dynamic-* kinds, the cascading-dependency pattern (e.g., channel depends on team), dynamic schema for body shapes, and a rule of thumb for what to bake into userParameters vs leave LLM-supplied. Mirror the same triage in SKILL.md Step 4B. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
User correction: 'audience is not a required field' on ManagedServiceIdentity callback auth. Updated the skill to treat it as optional and to always ASK the user whether to set one: - notification-authentication.md sec 4: audience-less example first, audience-with-value second; validation rules say 'optional, omit for non-AAD callbacks'. - SKILL.md auth-type table + STOP-and-ask list updated. - trigger-setup.md example shows audience commented out + gotcha table updated. - gotchas.md row replaced (was 'audience required', now 'fabricated audience -> always ask'). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
If the user doesn't provide an MSI audience, default to https://management.azure.com/ (a real AAD-protected resource — ARM). Never use the callback URL as the audience. Updated: - notification-authentication.md sec 4: workflow (ask -> use / default to ARM), examples lead with default-audience pattern, validation rule reverted to 'audience required, default if not given'. - SKILL.md auth-type table, rules table, STOP-and-ask list. - trigger-setup.md example shows default audience + comment, gotcha table updated. - gotchas.md row updated to reflect default-audience behavior. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
MCP server config access policies require BOTH a principal.type of 'ActiveDirectory' AND a sibling properties.principalType of 'User' or 'Group' (the shared ActiveDirectory enum is insufficient here). The access-policy resource name in the URL must equal the caller's objectId (case-insensitive). MIs/service principals are not supported as MCP principals - only Entra users and groups. Discovered while creating servicebus-send-aigateway MCP config on apseth-msi gateway. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The MCP runtime validates that every required Swagger parameter — including required body sub-properties — is declared in either userParameters (fixed value) or agentParameters (caller-supplied JSON Schema). Skipping this triage causes runtime failures like: The API operation 'SendEmailV2' is missing required property 'emailMessage/To'. Changes: - mcp-server-config.md: rewrote the parameter section to cover userParameters vs agentParameters, body decomposition (one agentParameter named after the body root with a nested object schema), and a STOP-and-ask triage workflow per parameter. Added the ConvertTo-Json depth gotcha and updated the PUT example to show both arrays. - SKILL.md: added the per-parameter triage rule + STOP-and-ask entry; updated Step 4B to enumerate body sub-properties and triage each one; updated the PUT example to include agentParameters. - gotchas.md: added rows for the "missing required property" runtime error and the ConvertTo-Json depth truncation symptom. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The trigger wizard (Cascade `serializeTriggerParams`) aggregates every body- sourced leaf — including dotted nested paths — into ONE `parameters[]` entry whose name is literally `"body"` (independent of the Swagger body parameter's own name, e.g. Teams declares it as `requestBody`) and whose `value` is the nested object. Non-body dotted leaves group under their root segment via `groupDottedEntriesToNestedObjects`. The skill previously only showed flat scalar examples and would have produced broken `body.<path>` dotted entries. Also calls out the wrapper-name asymmetry between MCP and triggers: - MCP: body wrapper name = Swagger body param's own name (e.g. `emailMessage`). - Trigger: body wrapper name = literal `"body"`, always. Changes: - trigger-setup.md: added §2a (per-parameter enumeration + STOP-and-ask) and §2b (wire-shape rules with a nested-body example and an anti-pattern). Bumped the PUT example to ConvertTo-Json -Depth 20. Added Common-Mistakes rows for flat dotted body names, wrong wrapper name, and depth truncation. - SKILL.md: rewrote Step 4A item 2 to spell out body decomposition and the literal `"body"` wrapper. Updated the rules table entry for "Trigger body schema" to document the wrapper convention. Clarified MCP triage rule to highlight the wrapper-name difference. - gotchas.md: added rows for "body leaves visible as flat dotted params" and "trigger body wrapper named after the Swagger param". Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Both MCP and trigger configs need to build nested-object payloads from per-leaf user answers. The previous commit covered the rules and shapes but didn't walk through the Swagger → user answers → assembled wire entry flow. Add concrete worked examples in both docs: - trigger-setup.md §2c: Teams PostMessageToChannelV3 → user picks team/channel, types message content, picks contentType → assembled as ONE entry named "body" (literal) with the recipient/messageBody sub-objects. - mcp-server-config.md "Worked example": SharePoint PostItem → user splits Title (agent), Status (user="Open"), Assignee.Email (agent), Tags (agent) → assembled as paired userParameters/agentParameters entries with the same root name "item" (Swagger body param's own name). The two examples make the user-vs-agent / fixed-vs-dynamic distinction and the wrapper-name asymmetry (literal "body" for triggers vs Swagger name for MCP) concrete. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Cascade portal has renamed the user-facing term to "Connector Namespace"
(see CreateConnectorNamespacePanel.tsx, ConnectorNamespaceIcon.tsx, the
CONNECTOR_NAMESPACE_REGIONS_* constants, etc.). Update the skill to match.
What changed:
- Folder: Skills/General/azure-connectorgateway/ ->
Skills/General/azure-connectornamespace/ (git mv preserves history).
- SKILL.md frontmatter: name -> azure-connectornamespace; description
rewritten with "Connector Namespace"; kept "connector gateway" as a
legacy discovery keyword so users searching the old term still hit
this skill.
- All prose in SKILL.md + references/*.md: "Connector Gateway"/"gateway"
-> "Connector Namespace"/"namespace" with proper case handling.
- Variable placeholders: {gw} -> {namespace}, $gw -> $namespace,
$gwBody -> $namespaceBody, $gwMi -> $namespaceMi, $gwTenant ->
$namespaceTenant.
- Example resource names: gateway-acl -> namespace-acl, tutorial-gw ->
tutorial-ns, <gateway-host> -> <namespace-host>.
- Added a "Naming note" section on SKILL.md explaining the rename and
what stayed unchanged.
- Added a gotchas.md row clarifying display name vs API strings.
What stayed unchanged (API contracts):
- ARM resource type: Microsoft.Web/connectorGateways (URL segment is
the live REST API path).
- Sandbox-group property: gatewayConnections[].
- RBAC string: Microsoft.Web/connectorGateways/*.
- Cascade source folder reference: src/.../ConnectorGateways/.
- Sandbox companion skill folder: Skills/Sandbox/azure-connectorgateway/
(separate skill, out of scope for this rebrand).
- Test class name: AIGatewayApiTests_NotificationAuthValidation_*.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new generic (sandbox-agnostic) Connector Namespace skill (azure-connectornamespace) with end-to-end documentation for managing namespaces, connections, trigger configs (webhook callbacks), and MCP server configs, and wires the skill into the repo’s marketplace/plugin manifests. Also updates the existing sandbox-focused azure-connectorgateway docs to clarify the required regional sandbox data-plane host for trigger callbacks and refreshes quickstart guidance.
Changes:
- Introduces
Skills/General/azure-connectornamespace/withSKILL.md, reference docs, andversion.json. - Updates
Skills/Sandbox/azure-connectorgatewaydocs to requirehttps://management.{region}.azuredevcompute.io/...for ShellCommand/ExecuteCommand callbacks and improves troubleshooting notes. - Registers the new skill in
README.md,marketplace.json, and both plugin manifests.
Reviewed changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| Skills/Sandbox/azure-connectorgateway/SKILL.md | Updates callback URL examples to require the regional sandbox data-plane host. |
| Skills/Sandbox/azure-connectorgateway/references/trigger-setup.md | Clarifies that ShellCommand callback URLs must use the regional host (unregional returns 404). |
| Skills/Sandbox/azure-connectorgateway/references/quickstart.md | Replaces notebook pointer with a docs-based end-to-end tutorial link. |
| Skills/Sandbox/azure-connectorgateway/references/gotchas.md | Expands troubleshooting guidance for regional endpoint 404s (incl. trigger callbackUrl). |
| Skills/General/azure-connectornamespace/version.json | Adds version metadata for the new skill. |
| Skills/General/azure-connectornamespace/SKILL.md | Adds the main generic Connector Namespace skill guide and workflows (triggers/MCP/direct API). |
| Skills/General/azure-connectornamespace/references/tutorial.md | Adds end-to-end walkthroughs to validate namespaces, triggers, and connections. |
| Skills/General/azure-connectornamespace/references/trigger-setup.md | Adds detailed trigger configuration guidance, including parameter shaping rules. |
| Skills/General/azure-connectornamespace/references/trigger-flow.md | Adds an architecture/lifecycle overview for triggers. |
| Skills/General/azure-connectornamespace/references/quickstart.md | Adds minimal “list everything” commands for namespaces/connections/triggers/MCP configs. |
| Skills/General/azure-connectornamespace/references/prerequisites.md | Adds prerequisites and provider registration guidance for the new skill. |
| Skills/General/azure-connectornamespace/references/notification-authentication.md | Documents callback authentication shapes and MSI audience rules. |
| Skills/General/azure-connectornamespace/references/mcp-server-config.md | Adds comprehensive MCP server config documentation, schema, and access policy rules. |
| Skills/General/azure-connectornamespace/references/gotchas.md | Adds common failure modes and fixes specific to connector namespaces + MCP + triggers. |
| Skills/General/azure-connectornamespace/references/dynamic-values.md | Documents how to resolve x-ms-dynamic-* parameters via Swagger + dynamicInvoke. |
| Skills/General/azure-connectornamespace/references/direct-api.md | Documents direct connector operation invocation via dynamicInvoke. |
| Skills/General/azure-connectornamespace/references/consent.md | Documents OAuth consent link generation for connections. |
| Skills/General/azure-connectornamespace/references/connections.md | Documents connection CRUD and access policy setup. |
| README.md | Adds the new skill to the “Available skills” table. |
| marketplace.json | Registers azure-connectornamespace as a marketplace plugin entry. |
| .plugin/plugin.json | Adds the new skill path to the plugin manifest skills list. |
| .claude-plugin/plugin.json | Adds the new skill path to the Claude plugin manifest skills list. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+93
to
+94
| > **ARM base:** `https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Web/connectorNamespaces` | ||
| > **API version:** `2026-05-01-preview` |
Comment on lines
+35
to
+37
| > **Naming note.** This skill was previously called "Connector Gateway". The | ||
| > resource is now displayed as **"Connector Namespace"** everywhere (matching | ||
| > the Cascade portal rename — see `Cascade.Portal.Client/src/components/CreateConnectorNamespacePanel.tsx`). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new
azure-connectornamespaceskill underSkills/General/with full SKILL.md and reference docs (connections, consent, direct-api, dynamic-values, gotchas, MCP server config, notification-authentication, prerequisites, quickstart, trigger-flow, trigger-setup, tutorial).Also rebrands "Connector Gateway" -> "Connector Namespace" (display only) and registers the new skill in
README.md,marketplace.json, and the plugin manifests.Changes
Skills/General/azure-connectornamespace/(SKILL.md + 12 reference docs + version.json)Skills/Sandbox/azure-connectorgatewaydocsCommits
783113c Adressed comments 5461a17 Fixed the skill 8a4fb14 Rebrand "Connector Gateway" -> "Connector Namespace" (display only) a78471c Add end-to-end worked examples for complex body assembly 8bd0ef8 Cover nested-object construction for trigger configs 8040186 Document agentParameters and per-parameter triage for MCP server configs a8c6be6 Fix MCP access-policy schema docs (User/Group + objectId path) c0626e8 MSI auth: default audience to https://management.azure.com/ cd08733 Fix: MSI audience is OPTIONAL, ask the user 41c35ce MCP config: explicit dynamic-values/list/tree/schema guidance 2b4a94e Add generic azure-connectorgateway skill