Rename 'API key' to 'Agent ID' to reduce security testing confusion

[lpcox]

Problem

The MCP Gateway uses the term "API key" (api_key / apiKey / MCP_GATEWAY_API_KEY) for a value that serves as an agent/session identifier, not a security credential. This causes confusion during security testing because:

1. Security reviewers expect an "API key" to be a secret that must be protected (rotated, stored in vaults, never logged)
2. In reality, this value is a session routing identifier — it determines which agent session receives requests
3. The gateway makes no attempt to protect this value as a secret (it's used as-is from the Authorization header and also serves as the session ID)
4. When no key is configured, the system still works — the value is optional and primarily identifies the caller

Current Architecture

The Authorization header value simultaneously:

• Acts as an authentication credential (compared against config value)
• Serves as the agent/session identity (routes requests, scopes DIFC labels, partitions sessions)

ParseAuthHeader() returns the same value as both apiKey and agentID. ExtractSessionID() uses the Authorization header value directly as session identity.

Proposed Changes

1. Rename terminology

Current	Proposed
api_key (TOML)	agent_id
apiKey (JSON stdin)	agentId
MCP_GATEWAY_API_KEY (env)	MCP_GATEWAY_AGENT_ID
APIKey (Go struct)	AgentID
GetAPIKey()	GetAgentID()
ValidateAPIKey()	ValidateAgentID()

2. Support X-Agent-ID header as alternative source

Accept the agent identifier from either:

• Authorization header (current behavior, for backward compat)
• X-Agent-ID header (new, explicit)

When both are present, X-Agent-ID takes precedence for session routing while Authorization is still used for auth validation.

Open question: It is unclear how easily an agent/harness would be able to set the X-Agent-ID header — this should be investigated during implementation. The Authorization header path must remain fully supported.

3. Backward compatibility

Accept both old and new config field names during a deprecation period:

• TOML: accept both api_key and agent_id (warn on old)
• JSON stdin: accept both apiKey and agentId (warn on old)
• Env var: check both MCP_GATEWAY_AGENT_ID and MCP_GATEWAY_API_KEY (warn on old)

Scope

~15 code files, ~10 test files, ~5 doc files. No behavioral change — purely a rename with compat aliases and the new optional header.

Migration Path

1. Phase 1 (this issue): Add new names + X-Agent-ID header support, emit deprecation warnings for old names
2. Phase 2 (future release): Remove old names from docs, keep parsing support
3. Phase 3 (breaking release): Remove old name support

Files Affected

Config: config_core.go, config_stdin.go, config_env.go, validation_env.go
Auth: internal/auth/header.go
Server: middleware.go, routed.go, http_server.go, handlers.go, unified.go
Schema: mcp-gateway-config.schema.json
Docs: README.md, CONFIGURATION.md, ENVIRONMENT_VARIABLES.md, AGENTS.md