Copilot Studio Agent Direct Line MCP Server

# ============================================================================= # Copilot Studio Agent Direct Line MCP Server - Environment Configuration # ============================================================================= # This file serves as a template for both local development and Azure deployment # Copy this file to .env and fill in your values # ============================================================================= # ----------------------------------------------------------------------------- # REQUIRED VARIABLES (ALL ENVIRONMENTS) # ----------------------------------------------------------------------------- # Direct Line API Secret Key (REQUIRED) # Obtain from Azure Bot Service > Channels > Direct Line # Format: alphanumeric string with dots, hyphens, or underscores # Example: your-secret-key-here.xxxxxxxxxxxxx DIRECT_LINE_SECRET= # Node Environment (REQUIRED) # Valid values: development | staging | production # Default: development # Affects validation requirements and security settings # - development: Relaxed validation, auto-generated secrets, allows HTTP # - staging: Stricter validation, HTTPS recommended # - production: Strictest validation, HTTPS required, all Azure auth required NODE_ENV=development # ----------------------------------------------------------------------------- # MCP TRANSPORT & AUTHENTICATION (OPTIONAL - Defaults Provided) # ----------------------------------------------------------------------------- # MCP Transport Mode (OPTIONAL) # Valid values: stdio | http # Default: stdio (local development), http (Azure Container Apps) # - stdio: Standard input/output for local MCP clients (Claude Desktop, VS Code) # - http: HTTP transport with OAuth for multi-user environments # MCP_TRANSPORT_MODE=stdio # Enable Authentication (OPTIONAL) # Set to 'true' to enable Azure Entra ID authentication even in stdio mode # Default: false (authentication only enabled automatically in HTTP mode) # ENABLE_AUTH=false # Require MCP Authentication (OPTIONAL) # Set to 'true' to require authentication for /mcp endpoint in HTTP mode # Default: false (allows unauthenticated MCP requests in development) # REQUIRE_MCP_AUTH=false # ----------------------------------------------------------------------------- # AZURE ENTRA ID / OAUTH2 CONFIGURATION # ----------------------------------------------------------------------------- # Required in production, optional in development # Obtain from Azure Portal > App registrations # Azure Entra ID Client ID (Application ID) # Format: UUID (e.g., 12345678-1234-1234-1234-123456789abc) # REQUIRED when NODE_ENV=production or ENABLE_AUTH=true AZURE_CLIENT_ID= # Azure Entra ID Client Secret # Minimum: 16 characters for security # REQUIRED when NODE_ENV=production or ENABLE_AUTH=true # Generate at: Azure Portal > App registrations > Certificates & secrets AZURE_CLIENT_SECRET= # Azure Entra ID Tenant ID (Directory ID) # Format: UUID or domain (e.g., 12345678-... or contoso.onmicrosoft.com) # REQUIRED when NODE_ENV=production or ENABLE_AUTH=true AZURE_TENANT_ID= # OAuth2 Redirect URI (OPTIONAL) # Where users are redirected after authentication # Must be HTTPS in production (except localhost) # Default: http://localhost:3000/auth/callback (local) # For Azure: https://<your-app-name>.azurecontainerapps.io/auth/callback # REDIRECT_URI=http://localhost:3000/auth/callback # OAuth2 Scopes (OPTIONAL) # Space-separated list of requested permissions # Default: openid profile email # Example: openid profile email https://graph.microsoft.com/.default OAUTH_SCOPES=openid profile email # ----------------------------------------------------------------------------- # HTTP SERVER CONFIGURATION (REQUIRED FOR HTTP MODE) # ----------------------------------------------------------------------------- # MCP Server Port (OPTIONAL) # Port for MCP server to listen on # Valid range: 1024-65535 # Default: Auto-assigned (local), 3000 (Azure) # MCP_SERVER_PORT=3000 # Session Secret (OPTIONAL) # Generate a strong random string (minimum 32 characters recommended) # Example: openssl rand -base64 32 # Auto-generated if not provided in development # REQUIRED in production when using HTTP mode # SESSION_SECRET= # Allowed CORS Origins (OPTIONAL) # Comma-separated list of allowed origins # Default: * (all origins in development), restricted in production # Example: http://localhost:3000,http://localhost:3001 # ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001 # Cookie Domain (OPTIONAL) # Domain for session cookies (e.g., .example.com) # Default: Not set (uses request domain) # COOKIE_DOMAIN= # Trust Proxy (OPTIONAL) # Set to 'true' if behind a load balancer or reverse proxy # Enables accurate IP addresses from X-Forwarded-* headers # Default: false (local), true (Azure Container Apps) # TRUST_PROXY=false # Enable Certificate Authentication (OPTIONAL) # Set to 'true' to enable mutual TLS client certificate authentication # Default: false # ENABLE_CERT_AUTH=false # ----------------------------------------------------------------------------- # APPLICATION CONFIGURATION (OPTIONAL) # ----------------------------------------------------------------------------- # Log Level (OPTIONAL) # Controls verbosity of application logging # Valid values: debug | info | warn | error # Default: info # LOG_LEVEL=info # Token Refresh Interval (OPTIONAL) # How often to proactively refresh Direct Line tokens (in milliseconds) # Minimum: 300000 (5 minutes) # Default: 1800000 (30 minutes) # Tokens are refreshed 5 minutes before expiration # TOKEN_REFRESH_INTERVAL=1800000 # ----------------------------------------------------------------------------- # AZURE INFRASTRUCTURE (REQUIRED FOR AZURE DEPLOYMENT) # ----------------------------------------------------------------------------- # These variables are required when deploying to Azure Container Apps # Set as GitHub Secrets for CI/CD deployment # Azure Subscription ID # Find in: Azure Portal > Subscriptions # Format: UUID (e.g., 12345678-1234-1234-1234-123456789abc) # AZURE_SUBSCRIPTION_ID= # Azure Location/Region # Examples: eastus, westus2, westeurope, etc. # Default: eastus # AZURE_LOCATION=eastus # Azure Container Registry Name # Must be globally unique, alphanumeric only, 5-50 characters # Example: mycompanyacr # AZURE_CONTAINER_REGISTRY_NAME= # Environment Name (for Azure deployment) # Valid values: dev | staging | prod # Determines resource sizing and configuration # Default: Derived from git branch (main=prod, develop=dev) # AZURE_ENV_NAME=dev # Container Image Tag (for Azure deployment) # Default: latest (local), git SHA (CI/CD) # For production, use semantic versioning (e.g., v1.0.0) # IMAGE_TAG=latest # ----------------------------------------------------------------------------- # MONITORING & OBSERVABILITY (AZURE DEPLOYMENT) # ----------------------------------------------------------------------------- # Enable Application Insights (OPTIONAL) # Default: true (Azure deployment), false (local) # ENABLE_MONITORING=true # Application Insights Connection String (AUTO-POPULATED) # Automatically populated after Azure deployment by Bicep templates # Leave empty - will be set by Azure deployment # APPLICATIONINSIGHTS_CONNECTION_STRING= # ----------------------------------------------------------------------------- # ADVANCED AZURE CONFIGURATION (OPTIONAL) # ----------------------------------------------------------------------------- # These override default values from azure.yaml environments # Defaults vary by environment (dev/staging/prod) # Minimum Replicas # Default: 1 (dev), 1 (staging), 2 (prod) # MIN_REPLICAS=1 # Maximum Replicas # Default: 3 (dev), 5 (staging), 10 (prod) # MAX_REPLICAS=10 # CPU per Container # Valid values: 0.25, 0.5, 0.75, 1.0, 1.25, 1.5, 1.75, 2.0 # Default: 0.25 (dev), 0.5 (staging), 1.0 (prod) # CPU=0.5 # Memory per Container # Valid values: 0.5Gi, 1.0Gi, 1.5Gi, 2.0Gi, 3.0Gi, 3.5Gi, 4.0Gi # Default: 0.5Gi (dev), 1.0Gi (staging), 2.0Gi (prod) # MEMORY=1.0Gi # ============================================================================= # DEPLOYMENT GUIDE # ============================================================================= # ----------------------------------------------------------------------------- # LOCAL DEVELOPMENT # ----------------------------------------------------------------------------- # 1. Copy this file: cp .env.example .env # 2. Fill in DIRECT_LINE_SECRET (obtain from Azure Bot Service) # 3. Optionally configure NODE_ENV=development (default) # 4. Run: npm run dev # # The server will start in stdio mode by default, ready for local MCP clients # like Claude Desktop, VS Code, or Cursor. # ----------------------------------------------------------------------------- # GITHUB ACTIONS DEPLOYMENT # ----------------------------------------------------------------------------- # Configure the following as GitHub Secrets for CI/CD workflow: # # Required Azure Infrastructure Secrets: # - AZURE_SUBSCRIPTION_ID (Azure subscription ID) # - AZURE_TENANT_ID (Entra ID tenant ID - for federated auth) # - AZURE_CLIENT_ID (Entra ID app client ID - for federated auth) # - AZURE_LOCATION (Azure region, default: eastus) # - AZURE_CONTAINER_REGISTRY_NAME (ACR name, must be globally unique) # # Required Application Secrets: # - DIRECT_LINE_SECRET (Bot Direct Line channel secret) # - SESSION_SECRET (Session encryption key, 32+ chars) # - ENTRA_CLIENT_ID (Entra ID app for user auth) # - ENTRA_CLIENT_SECRET (Entra ID app secret for user auth) # - ENTRA_TENANT_ID (Entra ID tenant for user auth) # # Note: ENTRA_* secrets are for user authentication (OAuth), while AZURE_* # secrets at the infrastructure level are for federated deployment authentication. # # The workflow (.github/workflows/azure-deploy.yml) will: # 1. Validate and build the application # 2. Deploy to Azure Container Apps using azd # 3. Set environment to dev/staging/prod based on branch or manual input # 4. Run health checks to verify deployment # ----------------------------------------------------------------------------- # MANUAL AZURE DEPLOYMENT # ----------------------------------------------------------------------------- # 1. Copy this file: cp .env.example .env # 2. Fill in Azure infrastructure variables (AZURE_SUBSCRIPTION_ID, etc.) # 3. Fill in application secrets (DIRECT_LINE_SECRET, SESSION_SECRET, etc.) # 4. Initialize Azure Developer CLI: azd init # 5. Login to Azure: azd auth login # 6. Deploy: azd up --environment <dev|staging|prod> # 7. View logs: azd logs # 8. Monitor: azd monitor # # For detailed deployment instructions, see DEPLOYMENT.md or SETUP_AND_DEPLOYMENT.md # ============================================================================= # IMPORTANT SECURITY NOTES # ============================================================================= # ⚠️ NEVER commit the actual .env file to version control # ⚠️ Add .env to .gitignore (should already be there) # ⚠️ Keep DIRECT_LINE_SECRET confidential - it provides full bot access # ⚠️ Keep AZURE_CLIENT_SECRET and SESSION_SECRET confidential # ⚠️ Use different secrets for development, staging, and production # ⚠️ Rotate secrets regularly (every 90 days recommended) # ⚠️ Set NODE_ENV=production to enforce security requirements # ⚠️ Use Azure Key Vault for production secrets (configured in Bicep) # ⚠️ For GitHub Actions, store secrets as GitHub Secrets, not in .env # ⚠️ Ensure HTTPS is enforced in production (automatic in Azure) # =============================================================================