Add mutually exclusive plural gateway agent ID configuration (#12116)

Adds plural gateway session identifiers for concurrent primary/enclave
configuration while retaining singular agent IDs. Singular and plural
forms are mutually exclusive.

- **Configuration**
- Adds `GatewayConfig.AgentIDs` (`agent_ids`) and stdin JSON
`gateway.agentIds`.
  - Preserves plural IDs during stdin-to-internal conversion.
- Rejects empty lists, blank entries, and singular/plural or
legacy-alias/plural combinations.

- **Published contract**
- Updates the bundled schema to require exactly one of `agentId` or
`agentIds`.
- Adds `agentIds` array constraints: `minItems: 1`, item `minLength: 1`.
- Removes `apiKey` from the published schema and configuration
documentation.

- **Compatibility and fixtures**
  - Keeps internal legacy `api_key` / `apiKey` parsing support.
  - Migrates schema-validated examples and test fixtures to `agentId`.

```toml
[gateway]
agent_ids = ["primary-agent", "enclave-agent"]
```

```json
{
  "gateway": {
    "agentIds": ["primary-agent", "enclave-agent"]
  }
}
```

<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes #12115

Author: lpcox

README.md

@@ -31,7 +31,7 @@ This gateway is used with [GitHub Agentic Workflows](https://github.com/github/g
    }
    ```
 
-   Note: for JSON stdin configuration the `gateway` section is **required**, and it must include `port`, `domain`, and one of `agentId` / `apiKey` (`apiKey` is a deprecated alias for `agentId`). The values shown above are examples; omitting `gateway` — or any of these required fields — fails schema validation at startup. All other `gateway` fields are optional and are validated when present. Optional server fields include `entrypoint`, `entrypointArgs`, `mounts`, `args`, `connectTimeout`, and `toolTimeout`; see [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for the complete server-field reference.
+   Note: for JSON stdin configuration the `gateway` section is **required**, and it must include `port`, `domain`, and exactly one of `agentId` or `agentIds`. The values shown above are examples; omitting `gateway` — or any of these required fields — fails schema validation at startup. All other `gateway` fields are optional and are validated when present. Optional server fields include `entrypoint`, `entrypointArgs`, `mounts`, `args`, `connectTimeout`, and `toolTimeout`; see [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for the complete server-field reference.
 
    Looking for complete examples? See [`config.example.toml`](config.example.toml), [`config.example-payload-threshold.toml`](config.example-payload-threshold.toml), and [`example-http-config.json`](example-http-config.json).
 
@@ -223,7 +223,7 @@ Key configuration fields (gateway-level under `[gateway]` in TOML / `"gateway"`
 | Field | Description |
 |-------|-------------|
 | `agent_id` / `agentId` | Agent/session identifier used for routing and optional auth matching |
-| `api_key` / `apiKey` | Deprecated alias for `agent_id` / `agentId` (accepted with warnings) |
+| `agent_ids` / `agentIds` | Agent/session identifiers for concurrent session isolation; configure exactly one of this field or `agent_id` / `agentId`. Each configured identifier authenticates independently, so concurrent primary/enclave sessions can each connect with their own credential. |
 | `port` | Metadata only; validated (1–65535) but does not control the listen address. Use the `--listen` flag to set the listen address. `MCP_GATEWAY_PORT` is read by `--validate-env` only as a required-variable presence check; port-mapping and listen-address construction are handled by wrapper scripts (`run.sh`, `run_containerized.sh`). |
 | `domain` | Gateway domain for external access (for example `"localhost"` in TOML/JSON, or `"${MCP_GATEWAY_DOMAIN}"` in JSON stdin where `${...}` expansion is supported) |
 | `startup_timeout` / `startupTimeout` | Seconds to wait for backend server startup (default `30`) |

config.example.toml

@@ -15,10 +15,10 @@
 # This field is stored for metadata purposes only. Valid range: 1-65535
 port = 3000
 
-# Agent ID for routing and optional authentication matching (optional)
-# When set, clients must provide this agent ID in the Authorization header
-# Format: Authorization: <agent_id>
-agent_id = ""
+# Agent IDs for concurrent session isolation and optional authentication matching (optional)
+# Configure either agent_id or agent_ids, but not both.
+# Clients must provide a configured agent ID in the Authorization header.
+agent_ids = ["primary-agent", "enclave-agent"]
 
 # Domain name for the gateway (optional)
 # Used for CORS and other domain-specific features

containers/serena-mcp-server/test-startup-time.sh

@@ -63,7 +63,7 @@ CONFIG_JSON=$(cat <<EOF
   "gateway": {
     "port": ${MCP_GATEWAY_PORT},
     "domain": "${MCP_GATEWAY_DOMAIN}",
-    "apiKey": "${MCP_GATEWAY_API_KEY}"
+    "agentId": "${MCP_GATEWAY_API_KEY}"
   }
 }
 EOF

docs/CONFIGURATION.md

@@ -592,7 +592,7 @@ The `customSchemas` top-level field allows you to define custom server types bey
 - **TOML format**:
   - Uses `command` and `args` fields directly (e.g., `command = "docker"`)
   - Variable expansion with `${VAR_NAME}` is only supported in `[gateway.opentelemetry]` fields (the legacy `[gateway.tracing]` section does **not** support variable expansion)
-  - Server `env` values, `url`, `args`, `gateway.agent_id`, and other non-tracing fields are not expanded
+  - Server `env` values, `url`, `args`, `gateway.agent_id` / `gateway.agent_ids`, and other non-tracing fields are not expanded
   - For host environment passthrough to container `env`, use an empty string `""` value
 - **Common rules** (both formats):
   - Empty/"local" type automatically normalized to "stdio"
@@ -609,7 +609,7 @@ The `customSchemas` top-level field allows you to define custom server types bey
 |-------|-------------|---------|
 | `port` | Validated and stored for metadata purposes only. The actual listen address is always set by the `--listen` CLI flag (default `127.0.0.1:3000`). **Note:** When using JSON stdin format, `gateway.port` is required by schema validation even though TOML configs have an internal default of `3000`. | `3000` (informational only; required in JSON stdin) |
 | `agentId` | Agent/session identifier used for routing and optional auth matching | (disabled) |
-| `apiKey` | Deprecated alias for `agentId` (accepted for backward compatibility) | (deprecated) |
+| `agentIds` (JSON stdin) / `agent_ids` (TOML) | Agent/session identifiers for concurrent session isolation. Configure exactly one of this field or `agentId` / `agent_id`; it must contain at least one non-blank string. Each configured identifier authenticates independently against the gateway (e.g. primary/enclave), enabling concurrent sessions that don't share a single credential. | (disabled) |
 | `domain` | Gateway domain (`"localhost"`, `"host.docker.internal"`, or `"${VAR}"`) | (unset) |
 | `startupTimeout` | Seconds to wait for backend startup | `30` |
 | `toolTimeout` | Maximum seconds for a single tool call, enforced as a context deadline on all backend requests (stdio and HTTP) | `60` |

guards/github-guard/scripts/run_copilot_test.sh

@@ -407,7 +407,7 @@ if [ "$MODE" = "yolo" ] || [ "$MODE" = "lockdown" ]; then
   "gateway": {
     "port": $GATEWAY_PORT,
     "domain": "localhost",
-    "apiKey": "$GATEWAY_API_KEY"
+    "agentId": "$GATEWAY_API_KEY"
   }
 }
 EOF
@@ -436,7 +436,7 @@ else
   "gateway": {
     "port": $GATEWAY_PORT,
     "domain": "localhost",
-    "apiKey": "$GATEWAY_API_KEY"
+    "agentId": "$GATEWAY_API_KEY"
   }
 }
 EOF

guards/github-guard/scripts/run_integration_tests.sh

@@ -201,7 +201,7 @@ echo ""
   "gateway": {
     "port": $GATEWAY_PORT,
     "domain": "localhost",
-    "apiKey": "$GATEWAY_API_KEY"
+    "agentId": "$GATEWAY_API_KEY"
   }
 }
 EOF

internal/cmd/output.go

@@ -46,8 +46,14 @@ func writeGatewayConfig(cfg *config.Config, listenAddr, mode string, tlsEnabled
 
 	debugLog.Printf("Resolved gateway address: host=%s, port=%s", host, port)
 
-	// Extract agent ID from gateway config (per spec section 7.1)
-	agentID := cfg.GetAgentID()
+	// Extract agent ID from gateway config (per spec section 7.1). When multiple
+	// identities are configured via gateway.agentIds, the first is used for this
+	// downstream-facing config; every configured identity is independently valid
+	// for authenticating directly against the gateway.
+	var agentID string
+	if ids := cfg.GetAgentIDs(); len(ids) > 0 {
+		agentID = ids[0]
+	}
 	debugLog.Printf("Gateway config: auth_enabled=%v", agentID != "")
 
 	debugLog.Printf("Gateway auth: agentIDConfigured=%v", agentID != "")

internal/cmd/root.go

@@ -288,7 +288,9 @@ func run(cmd *cobra.Command, args []string) error {
 	// Per spec §7.3: generate a random agent identifier on startup if none is configured.
 	// The generated value is set in the config so it propagates to both the HTTP
 	// server authentication and the stdout configuration output (spec §5.4).
-	if cfg.GetAgentID() == "" {
+	// gateway.agentIds (plural) counts as configured here, so a random ID is only
+	// generated when neither the singular nor plural form is set.
+	if len(cfg.GetAgentIDs()) == 0 {
 		randomKey, err := auth.GenerateRandomAgentID()
 		if err != nil {
 			return fmt.Errorf("failed to generate random agent ID: %w", err)
@@ -363,7 +365,7 @@ func run(cmd *cobra.Command, args []string) error {
 	}()
 
 	// Create HTTP server based on mode, wire BaseContext and shutdown hooks.
-	httpServer := buildHTTPServer(ctx, mode, listenAddr, unifiedServer, cfg.GetAgentID(), hmacSecret, cancel)
+	httpServer := buildHTTPServer(ctx, mode, listenAddr, unifiedServer, cfg.GetAgentIDs(), hmacSecret, cancel)
 
 	// Build net.Listener — optionally wrapping with TLS (ASI-07 Phase 1).
 	// Plain HTTP is still used when no TLS certificate is configured (backward compatible).

internal/cmd/run_test.go

@@ -215,3 +215,54 @@ func TestRun_InvalidGuardsMode(t *testing.T) {
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "invalid --guards-mode flag")
 }
+
+// TestRun_PluralAgentIDsStartsSuccessfully verifies that run() starts normally
+// when only gateway.agentIds (plural) is configured: every configured
+// identifier is accepted as a valid Authorization credential (see
+// config.Config.GetAgentIDs and authMiddleware's matchesAnyKey), enabling
+// concurrent primary/enclave sessions that each authenticate independently.
+func TestRun_PluralAgentIDsStartsSuccessfully(t *testing.T) {
+	resetRunFlagsForTest(t)
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.toml")
+	content := `[gateway]
+port = 3000
+agent_ids = ["primary-agent", "enclave-agent"]
+
+[servers.testserver]
+type = "http"
+url = "http://127.0.0.1:1"
+`
+	require.NoError(t, os.WriteFile(path, []byte(content), 0o600))
+
+	configFile = path
+	configStdin = false
+	envFile = ""
+	listenAddr = "127.0.0.1:0"
+	routedMode = true
+	unifiedMode = false
+	logDir = t.TempDir()
+	wasmCacheDir = t.TempDir()
+	shutdownTimeout = 2 * time.Second
+	difcMode = "strict"
+
+	ctx, cancel := context.WithCancel(context.Background())
+	rootCmd.SetContext(ctx)
+	t.Cleanup(func() { rootCmd.SetContext(context.Background()) })
+
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- run(rootCmd, nil)
+	}()
+
+	time.Sleep(200 * time.Millisecond)
+	cancel()
+
+	select {
+	case err := <-errCh:
+		assert.NoError(t, err, "run() should start successfully with only gateway.agentIds configured")
+	case <-time.After(5 * time.Second):
+		t.Fatal("run() did not return within the expected shutdown window")
+	}
+}

internal/cmd/startup.go

@@ -69,20 +69,20 @@ func buildHTTPServer(
 	ctx context.Context,
 	mode, listenAddr string,
 	unifiedServer *server.UnifiedServer,
-	agentID, hmacSecret string,
+	agentIDs []string, hmacSecret string,
 	cancel context.CancelFunc,
 ) *http.Server {
 	debugLog.Printf("Building HTTP server: mode=%s, listenAddr=%s, authEnabled=%v, hmacEnabled=%v",
-		mode, listenAddr, agentID != "", hmacSecret != "")
+		mode, listenAddr, len(agentIDs) > 0, hmacSecret != "")
 	var httpServer *http.Server
 	if mode == "routed" {
 		logger.StartupInfo("Starting MCPG in ROUTED mode on %s", listenAddr)
 		logger.StartupInfo("Routes: /mcp/<server> where <server> is one of: %v", unifiedServer.GetServerIDs())
-		httpServer = server.CreateHTTPServerForRoutedMode(listenAddr, unifiedServer, agentID, hmacSecret)
+		httpServer = server.CreateHTTPServerForRoutedMode(listenAddr, unifiedServer, agentIDs, hmacSecret)
 	} else {
 		logger.StartupInfo("Starting MCPG in UNIFIED mode on %s", listenAddr)
 		logger.StartupInfo("Endpoint: /mcp")
-		httpServer = server.CreateHTTPServerForMCP(listenAddr, unifiedServer, agentID, hmacSecret)
+		httpServer = server.CreateHTTPServerForMCP(listenAddr, unifiedServer, agentIDs, hmacSecret)
 	}
 
 	// Set BaseContext so every incoming request inherits the startup context,