From 07ca371679bffbb7baa4e45c4c659e1e6392c54f Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 11 Jun 2026 10:13:30 +0000
Subject: [PATCH] docs(site): document well-known MCP names and automatic
 network allowlisting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When an mcp-servers: key matches a recognised service identifier
(kusto, icm, bluebird, es-chat, msft-learn, asa, stack, calculator,
github), the compiler automatically adds that service's required hosts
to the AWF network allowlist — no manual network.allowed: entries needed.

Add a new '## Well-Known MCP Names and Automatic Networking' section to
site/src/content/docs/reference/mcp.mdx with a reference table and
example, plus a note distinguishing ado/ado-ext from user-defined MCPs.

Also correct the misleading Security Notes item 4 which previously stated
'Users must explicitly allow external domains via network.allowed' without
noting the well-known-name exception.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 site/src/content/docs/reference/mcp.mdx | 42 ++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/site/src/content/docs/reference/mcp.mdx b/site/src/content/docs/reference/mcp.mdx
index 8c54ed11..183b208d 100644
--- a/site/src/content/docs/reference/mcp.mdx
+++ b/site/src/content/docs/reference/mcp.mdx
@@ -140,9 +140,49 @@ network:
     - "*.dev.azure.com"
 ```
 
+## Well-Known MCP Names and Automatic Networking
+
+When the key under `mcp-servers:` matches a recognised service identifier, the
+compiler automatically adds that service's required hosts to the AWF network
+allowlist — no manual `network.allowed:` entries needed.
+
+| MCP name | Automatically allowed hosts |
+|----------|-----------------------------|
+| `kusto` | `*.kusto.windows.net`, `*.kusto.azure.com`, `*.kustomfa.windows.net`, `kusto.azure.com` |
+| `icm` | `icm.ad.msft.net`, `prod.microsofticm.com`, `*.microsofticm.com` |
+| `bluebird` | `bluebird.microsoft.com`, `*.bluebird.microsoft.com` |
+| `es-chat` | `es-chat.microsoft.com`, `*.es-chat.microsoft.com` |
+| `msft-learn` | `learn.microsoft.com`, `docs.microsoft.com`, `*.learn.microsoft.com` |
+| `asa` | `*.azure.com`, `asa.azure.com` |
+| `stack` | `stack.microsoft.com`, `*.stack.microsoft.com` |
+| `calculator` | *(no network required)* |
+| `github` | `api.github.com`, `github.com`, `*.githubusercontent.com` *(already in core)* |
+
+Any other name falls through to the generic path — the compiler adds no hosts
+automatically and the server must rely on what is already in the [default
+allowlist](/ado-aw/reference/network/#default-allowed-domains) or on explicit
+`network.allowed:` entries.
+
+```yaml
+# Kusto MCP — no network.allowed needed; the compiler infers the hosts
+mcp-servers:
+  kusto:
+    url: "https://kusto-mcp.example.com"
+    allowed:
+      - query_database
+      - list_tables
+```
+
+:::note[First-party tools use separate names]
+The identifiers `ado` and `ado-ext` are reserved for the first-party
+`tools.azure-devops` integration. Using them as user-defined `mcp-servers:`
+keys is technically valid but unusual — prefer `tools.azure-devops: true` for
+the standard ADO MCP setup (see [Tools configuration](/ado-aw/reference/tools/#azure-devops-mcp-azure-devops)).
+:::
+
 ## Security Notes
 
 1. **Two-level allow-listing**: Both `--allow-tool <server>` (CLI layer) and `allowed:` (MCPG layer) must grant permission for a tool call to succeed. See [Two-Level Permission Model](#two-level-permission-model) for details.
 2. **Containerization**: Stdio MCP servers run as isolated Docker containers (per MCPG spec §3.2.1).
 3. **Environment Isolation**: MCP containers are spawned by MCPG with only the configured environment variables.
-4. **Network Isolation**: MCP containers run within the same AWF-isolated network. Users must explicitly allow external domains via `network.allowed`.
+4. **Network Isolation**: MCP containers run within the same AWF-isolated network. For unknown MCP names, you must explicitly allow external domains via `network.allowed:`. Well-known MCP names (see [above](#well-known-mcp-names-and-automatic-networking)) get their required hosts added automatically.