MCP Gateway

The MCP Gateway deployment creates a multi-layered architecture in Azure consisting of the following components:

Core Infrastructure

• Azure Kubernetes Service (AKS): A 2-node cluster using D4ds_v5 VMs with Azure RBAC, OIDC issuer, and Workload Identity enabled.
• Azure Container Registry (ACR): Standard SKU for container image storage, integrated with AKS.
• Azure Cosmos DB: Document database for gateway state (AdapterContainer, CacheContainer, ToolContainer) using session consistency.

Networking

• Virtual Network (VNet): Includes subnets for AKS (10.0.1.0/24), Application Gateway (10.0.2.0/24), and Private Endpoints (10.0.3.0/24).
• Application Gateway: Standard_v2 SKU acting as a Layer 7 load balancer on port 80.
• Public IP: Static public IP with a DNS label.

Identity & Access

• Managed Identities: Includes Gateway service identity (Cosmos DB contributor), Admin identity (AKS operations), and Workload identity (pod-level auth).
• Federated Credentials: Enables Kubernetes service account integration.

Monitoring

• Application Insights: Provides application monitoring and telemetry.

To use MCP Gateway effectively, you should understand its core abstractions:

• MCP Server: A server implementing the Model Context Protocol, typically exposed as a streamable HTTP endpoint.
• Adapters: Logical resources representing MCP servers within the gateway, managed under the /adapters scope. They allow MCP servers to coexist with other resource types like /agents.
• Tools: Registered resources containing MCP tool definitions. These can be dynamically routed via the tool gateway router and include metadata for execution endpoints and input schemas.
• Tool Gateway Router: An MCP server that acts as an intelligent router. It directs tool execution requests to the correct registered tool servers based on their definitions. Multiple instances can run for session affinity.
• Session-Aware Stateful Routing: A mechanism that ensures all requests sharing a specific session_id are consistently routed to the same MCP server instance.
• Agents & Sessions (Preview): Opt-in features for running LLM-driven agents.
  • Agents are metadata consisting of a system prompt, a model, and an allowed tool list.
  • Sessions are individual runs that stream events via Server-Sent Events (SSE).
  • Note: These are disabled unless FoundrySettings:Endpoint is configured.

The portal automatically adjusts its authentication behavior based on the configuration returned from the GET /portal/config endpoint.

Local / Dev Mode

When isDevelopment: true is returned:

• The portal skips MSAL (Microsoft Authentication Library).
• It uses a DevelopmentAuthenticationHandler on the gateway which uses a synthetic dev principal.
• Users can optionally select a synthetic identity (user ID, display name, roles). These are forwarded to the gateway via the following headers:
  • X-Dev-UserId
  • X-Dev-Name
  • X-Dev-Roles

Cloud / Production Mode

When running in production:

• The portal initializes @azure/msal-browser using the tenant and client ID provided by /portal/config.
• Users sign in via a redirect flow.
• The portal acquires an access token with the api://<clientId>/.default scope.
• Every API call includes the token in the Bearer authorization header.

Once FoundrySettings is configured, you can define agents and run interactive sessions.

Defining an Agent: Agents are created via POST /agents. Tools in the tools array are namespaced:

• mcp:<tool-name>: Routes to a tool registered via /tools.
• agent:<agent-name>: Delegates to another agent (subagent/Task pattern).
• builtin:bash, builtin:read_file, builtin:write_file: In-process built-in tools.

POST /agents
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "weather-helper",
  "model": "gpt-4o",
  "system": "You answer weather questions concisely.",
  "tools": ["mcp:weather"],
  "description": "Demo agent backed by the weather MCP tool."
}

Running a Session: Start a session using POST /sessions/run. This returns a Server-Sent Events (SSE) stream. Event types include Started, ToolCallStarted, ToolCallCompleted, TokenDelta, Completed, and Failed.

POST /sessions/run
Authorization: Bearer <token>
Content-Type: application/json
Accept: text/event-stream

{ "agentName": "weather-helper", "input": "What's the weather in Seattle?" }

Continuing a Session: To send a follow-up message to an existing session, use POST /sessions/{id}/messages.

POST /sessions/{id}/messages
Content-Type: application/json

{ "input": "And in Portland?" }

You can deploy the infrastructure directly using Bicep via the Azure CLI. This method is considered legacy compared to the PowerShell script.

Deployment Steps

1. Create a resource group:

   az group create --name rg-mcpgateway-dev --location eastus

2. Deploy the Bicep template:

   az deployment group create \
     --name mcpgateway-deployment \
     --resource-group rg-mcpgateway-dev \
     --template-file azure-deployment.bicep \
     --parameters clientId=<your-entra-client-id>

Additional Bicep Parameters

• resourceLabel: Alphanumeric suffix for naming.
• location: Azure region.
• enablePrivateEndpoints: Set to true to enable private endpoints.
• enableKubernetesDeploymentScript: Set to false to disable the embedded Kubernetes deployment script.

# Deploy using Bicep with additional parameters
az deployment group create \
  --name mcpgateway-deployment \
  --resource-group rg-mcpgateway-dev \
  --template-file azure-deployment.bicep \
  --parameters \
    clientId=<your-entra-client-id> \
    resourceLabel=mcpdev \
    location=westus2 \
    enablePrivateEndpoints=true