refactor: apply Bicep best practices and fix token issuer mismatch

Bicep improvements:
- Add @description() decorators to all parameters in aca.bicep,
  aca-noauth.bicep, keycloak.bicep, and http-routes.bicep
- Remove redundant dependsOn in http-routes.bicep (implicit via existing)

Token issuer fix:
- Update write_env.sh and write_env.ps1 to use direct Keycloak URL
  for KEYCLOAK_REALM_URL instead of routed URL
- Fixes 401 Unauthorized errors caused by issuer mismatch between
  token's iss claim and MCP server's expected issuer
- Add MCP_SERVER_URL to env scripts for local agent testing

Author: madebygps

infra/aca-noauth.bicep

@@ -1,17 +1,42 @@
 // MCP Server WITHOUT Keycloak authentication (deployed_mcp.py)
+
+@description('Name of the MCP server container app')
 param name string
+
+@description('Azure region for deployment')
 param location string = resourceGroup().location
+
+@description('Tags to apply to all resources')
 param tags object = {}
 
+@description('User assigned identity name for ACR pull and Azure service access')
 param identityName string
+
+@description('Name of the Container Apps environment')
 param containerAppsEnvironmentName string
+
+@description('Name of the Azure Container Registry')
 param containerRegistryName string
+
+@description('Service name for azd tagging')
 param serviceName string = 'mcpnoauth'
+
+@description('Whether the container app already exists (for updates)')
 param exists bool
+
+@description('Azure OpenAI deployment name')
 param openAiDeploymentName string
+
+@description('Azure OpenAI endpoint URL')
 param openAiEndpoint string
+
+@description('Cosmos DB account name')
 param cosmosDbAccount string
+
+@description('Cosmos DB database name')
 param cosmosDbDatabase string
+
+@description('Cosmos DB container name')
 param cosmosDbContainer string
 
 resource mcpNoAuthIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {

infra/aca.bicep

@@ -1,21 +1,49 @@
+@description('Name of the MCP server container app')
 param name string
+
+@description('Azure region for deployment')
 param location string = resourceGroup().location
+
+@description('Tags to apply to all resources')
 param tags object = {}
 
+@description('User assigned identity name for ACR pull and Azure service access')
 param identityName string
+
+@description('Name of the Container Apps environment')
 param containerAppsEnvironmentName string
+
+@description('Name of the Azure Container Registry')
 param containerRegistryName string
+
+@description('Service name for azd tagging')
 param serviceName string = 'aca'
+
+@description('Whether the container app already exists (for updates)')
 param exists bool
+
+@description('Azure OpenAI deployment name')
 param openAiDeploymentName string
+
+@description('Azure OpenAI endpoint URL')
 param openAiEndpoint string
+
+@description('Cosmos DB account name')
 param cosmosDbAccount string
+
+@description('Cosmos DB database name')
 param cosmosDbDatabase string
+
+@description('Cosmos DB container name')
 param cosmosDbContainer string
 
-// Keycloak authentication parameters
+@description('Keycloak realm URL for token validation')
 param keycloakRealmUrl string
+
+@description('Base URL of the MCP server (for OAuth metadata)')
 param mcpServerBaseUrl string
+
+@description('Expected audience claim in JWT tokens')
 param mcpServerAudience string = 'mcp-server'
 
 resource acaIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {

infra/http-routes.bicep

@@ -1,6 +1,13 @@
+@description('Name of the Container Apps environment')
 param containerAppsEnvironmentName string
+
+@description('Name of the MCP server container app')
 param mcpServerAppName string
+
+@description('Name of the Keycloak container app')
 param keycloakAppName string
+
+@description('Name for the HTTP route configuration')
 param routeConfigName string = 'mcproutes'
 
 resource containerEnv 'Microsoft.App/managedEnvironments@2024-10-02-preview' existing = {
@@ -63,10 +70,7 @@ resource httpRouteConfig 'Microsoft.App/managedEnvironments/httpRouteConfigs@202
       }
     ]
   }
-  dependsOn: [
-    mcpServerApp
-    keycloakApp
-  ]
+  // Note: dependsOn not needed - 'existing' resources create implicit dependencies
 }
 
 output fqdn string = httpRouteConfig.properties.fqdn

infra/keycloak.bicep

@@ -1,13 +1,29 @@
+@description('Name of the Keycloak container app')
 param name string
+
+@description('Azure region for deployment')
 param location string = resourceGroup().location
+
+@description('Tags to apply to all resources')
 param tags object = {}
 
+@description('Name of the Container Apps environment')
 param containerAppsEnvironmentName string
+
+@description('Name of the Azure Container Registry')
 param containerRegistryName string
+
+@description('Service name for azd tagging')
 param serviceName string = 'keycloak'
+
+@description('Keycloak admin username')
 param keycloakAdminUser string = 'admin'
+
 @secure()
+@description('Keycloak admin password')
 param keycloakAdminPassword string
+
+@description('Whether the container app already exists (for updates)')
 param exists bool
 
 @description('User assigned identity name for ACR pull')

infra/write_env.ps1

@@ -11,4 +11,7 @@ Add-Content -Path $ENV_FILE_PATH -Value "AZURE_TENANT_ID=$(azd env get-value AZU
 Add-Content -Path $ENV_FILE_PATH -Value "AZURE_COSMOSDB_ACCOUNT=$(azd env get-value AZURE_COSMOSDB_ACCOUNT)"
 Add-Content -Path $ENV_FILE_PATH -Value "AZURE_COSMOSDB_DATABASE=$(azd env get-value AZURE_COSMOSDB_DATABASE)"
 Add-Content -Path $ENV_FILE_PATH -Value "AZURE_COSMOSDB_CONTAINER=$(azd env get-value AZURE_COSMOSDB_CONTAINER)"
+# Use direct Keycloak URL for token requests (issuer must match what MCP server expects)
+Add-Content -Path $ENV_FILE_PATH -Value "KEYCLOAK_REALM_URL=$(azd env get-value KEYCLOAK_DIRECT_URL)/realms/mcp"
+Add-Content -Path $ENV_FILE_PATH -Value "MCP_SERVER_URL=$(azd env get-value MCP_SERVER_URL)/mcp"
 Add-Content -Path $ENV_FILE_PATH -Value "API_HOST=azure"

infra/write_env.sh

@@ -15,4 +15,7 @@ echo "AZURE_TENANT_ID=$(azd env get-value AZURE_TENANT_ID)" >> "$ENV_FILE_PATH"
 echo "AZURE_COSMOSDB_ACCOUNT=$(azd env get-value AZURE_COSMOSDB_ACCOUNT)" >> "$ENV_FILE_PATH"
 echo "AZURE_COSMOSDB_DATABASE=$(azd env get-value AZURE_COSMOSDB_DATABASE)" >> "$ENV_FILE_PATH"
 echo "AZURE_COSMOSDB_CONTAINER=$(azd env get-value AZURE_COSMOSDB_CONTAINER)" >> "$ENV_FILE_PATH"
+# Use direct Keycloak URL for token requests (issuer must match what MCP server expects)
+echo "KEYCLOAK_REALM_URL=$(azd env get-value KEYCLOAK_DIRECT_URL)/realms/mcp" >> "$ENV_FILE_PATH"
+echo "MCP_SERVER_URL=$(azd env get-value MCP_SERVER_URL)/mcp" >> "$ENV_FILE_PATH"
 echo "API_HOST=azure" >> "$ENV_FILE_PATH"