feat (iac): [networking] add MCP subnet (#106)

* reserve private MCP server subnet

Prepare the workload virtual network for privately hosted MCP servers:
- reserve a dedicated /24 subnet
- delegate the subnet to Microsoft.App/environments
- expose the subnet name and resource ID

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* secure private MCP server subnet

Apply deny-by-default controls for a future Container Apps environment:
- allow required platform, DNS, load-balancer, and intra-subnet traffic
- allow access to workload private endpoints
- attach the NSG to the reserved MCP subnet

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* allow private agent MCP traffic

Enable the private MCP request path within the workload virtual network:
- allow Foundry Agent outbound HTTPS to the MCP subnet
- allow matching inbound HTTPS on the MCP subnet

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* route MCP egress through firewall

Control private MCP server outbound traffic through Azure Firewall:
- associate the MCP subnet with the egress route table
- allow required Container Apps platform dependencies
- wire the MCP subnet into the firewall module

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* document private MCP network path

Clarify how agents reach public and private MCP servers:
- describe firewall-controlled public MCP egress
- identify the reserved private MCP subnet
- note that the Container Apps environment is not deployed

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR Feedback: clarify probe ports

Document the Container Apps load-balancer probe rule lifecycle:
- retain the required dynamic allocation range initially
- narrow the NSG rule after Azure assigns the immutable ports

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: ferantivero

README.md

@@ -39,7 +39,7 @@ Microsoft Foundry hosts Foundry Agent Service as a capability. Foundry Agent ser
 1. When the web application receives a message, it passes it along with the conversation ID to the Foundry prompt-based agent through the [Microsoft Agent Framework](https://github.com/microsoft/agent-framework), which calls the [OpenAI Conversations](https://ai.azure.com/api-reference/conversations/create-conversation/) and [Responses](https://ai.azure.com/api-reference/responses/create-response/) APIs under the hood. The web application calls the agent over a private endpoint and authenticates to Foundry by using its managed identity.
 1. The agent processes the user's request based on the instructions in its system prompt. To fulfill the user's intent, the agent uses a configured language model and connected tools and knowledge stores.
 1. The agent connects to the knowledge store (Azure AI Search) in the private network via a private endpoint.
-1. Requests to most external knowledge stores or tools, such as Wikipedia, traverse Azure Firewall for inspection and egress policy enforcement. Some of Foundry's built-in connections might not support egressing through your subnet.
+1. Requests to approved public tools, such as public MCP servers, traverse Azure Firewall for inspection and egress policy enforcement. Calls to private MCP servers use private addressing to reach a dedicated subnet in the workload virtual network. The implementation reserves and secures this delegated subnet but doesn't deploy an MCP server or Azure Container Apps environment.
 1. The agent connects to its configured language model and passes relevant context.
 1. Before the agent returns the response to the UI, it persists the request, the generated response, and a list of consulted knowledge stores into a dedicated memory database. This database maintains the complete conversation history, which enables context-aware interactions and allows users to resume conversations with the agent without losing prior context.
 

infra-as-code/bicep/azure-firewall.bicep

@@ -16,6 +16,10 @@ param logAnalyticsWorkspaceName string
 @minLength(8)
 param agentsEgressSubnetName string
 
+@description('The name of the subnet reserved for private MCP servers. Must be in the same virtual network that is provided.')
+@minLength(8)
+param mcpServersSubnetName string
+
 @description('The name of the subnet containing your jump boxes. Must be in the same virtual network that is provided.')
 @minLength(8)
 param jumpBoxesSubnetName string
@@ -34,6 +38,10 @@ resource virtualNetwork 'Microsoft.Network/virtualNetworks@2025-07-01' existing
     name: agentsEgressSubnetName
   }
 
+  resource mcpServersSubnet 'subnets' existing = {
+    name: mcpServersSubnetName
+  }
+
   resource jumpBoxesSubnet 'subnets' existing = {
     name: jumpBoxesSubnetName
   }
@@ -98,6 +106,29 @@ resource azureFirewallPolicy 'Microsoft.Network/firewallPolicies@2025-07-01' = {
     properties: {
       priority: 200
       ruleCollections: [
+        {
+          ruleCollectionType: 'FirewallPolicyFilterRuleCollection'
+          name: 'mcp-platform-egress'
+          priority: 900
+          action: {
+            type: 'Allow'
+          }
+          rules: [
+            {
+              ruleType: 'NetworkRule'
+              name: 'allow-container-apps-platform'
+              ipProtocols: ['TCP']
+              sourceAddresses: ['${virtualNetwork::mcpServersSubnet.properties.addressPrefix}']
+              destinationAddresses: [
+                'MicrosoftContainerRegistry'
+                'AzureFrontDoor.FirstParty'
+                'AzureActiveDirectory'
+                'AzureMonitor'
+              ]
+              destinationPorts: ['443']
+            }
+          ]
+        }
         {
           ruleCollectionType: 'FirewallPolicyFilterRuleCollection'
           name: 'jump-box-egress'
@@ -126,6 +157,39 @@ resource azureFirewallPolicy 'Microsoft.Network/firewallPolicies@2025-07-01' = {
     properties: {
       priority: 300
       ruleCollections: [
+        {
+          ruleCollectionType: 'FirewallPolicyFilterRuleCollection'
+          name: 'mcp-server-egress'
+          priority: 900
+          action: {
+            type: 'Allow'
+          }
+          rules: [
+            {
+              ruleType: 'ApplicationRule'
+              name: 'allow-container-apps-dependencies'
+              protocols: [
+                {
+                  protocolType: 'Https'
+                  port: 443
+                }
+              ]
+              fqdnTags: []
+              webCategories: []
+              targetFqdns: [
+                'packages.aks.azure.com'
+                'acs-mirror.azureedge.net'
+                '*.identity.azure.net'
+                // 'api.example.org' // Add the public FQDNs that your MCP servers require.
+              ]
+              targetUrls: []
+              terminateTLS: false
+              sourceAddresses: ['${virtualNetwork::mcpServersSubnet.properties.addressPrefix}']
+              destinationAddresses: []
+              httpHeadersToInsert: []
+            }
+          ]
+        }
         {
           ruleCollectionType: 'FirewallPolicyFilterRuleCollection'
           name: 'agent-egress'

infra-as-code/bicep/main.bicep

@@ -86,6 +86,7 @@ module deployAzureFirewall 'azure-firewall.bicep' = {
     logAnalyticsWorkspaceName: logAnalyticsWorkspace.name
     virtualNetworkName: deployVirtualNetwork.outputs.virtualNetworkName
     agentsEgressSubnetName: deployVirtualNetwork.outputs.agentsEgressSubnetName
+    mcpServersSubnetName: deployVirtualNetwork.outputs.mcpServersSubnetName
     jumpBoxesSubnetName: deployVirtualNetwork.outputs.jumpBoxesSubnetName
   }
 }