Skip to content

docs(site): document well-known MCP names and automatic network allowlisting #967

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
github-actions wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(site): document well-known MCP names and automatic network allowlisting #967

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 41 additions & 1 deletion site/src/content/docs/reference/mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.