Enforce MCP spec OAuth 2.1 authorization requirements

[Copilot]

The gateway's authorization implementation deviated from the MCP specification (2025-03-26) in several ways: accepting plain API keys without Bearer prefix, allowing tokens in query strings, and lacking validation for malformed authorization headers.

Changes

Authorization Middleware (internal/server/auth.go)

• Enforce strict Authorization: Bearer <token> format per OAuth 2.1
• Reject tokens in query parameters (?token=, ?access_token=, ?apiKey=)
• Return HTTP 400 for malformed headers (missing Bearer prefix, empty tokens)
• Return HTTP 401 for invalid/missing tokens
• Document HTTP 403 reserved for future scope-based permissions

Architecture Documentation (docs/AUTHORIZATION.md)

• Two-layer architecture: auth middleware validates token, transport layer extracts session ID
• HTTP status code semantics per MCP spec
• Configuration patterns for dev vs production
• Security considerations and future OAuth scope support

Tests (internal/server/auth_test.go)

11 test cases covering:

• Bearer format validation
• Query string rejection
• Empty/whitespace token handling
• Case sensitivity
• Multiple authorization headers

Updated Existing Tests

Modified integration_test.go and routed_test.go to use Bearer format:

// Before
req.Header.Set("Authorization", apiKey)

// After
req.Header.Set("Authorization", "Bearer "+apiKey)

Transport Layer Comments

Added clarifying comments in transport.go and routed.go explaining that these layers extract Bearer tokens for session identification only—token validation happens in auth middleware when API key is configured.

Compliance

MCP Spec Requirement	Status
Bearer token format	✅ Enforced
No tokens in query strings	✅ Validated
HTTP 400 for malformed auth	✅ Implemented
HTTP 401 for invalid tokens	✅ Implemented
HTTP 403 for insufficient permissions	✅ Documented (future OAuth scopes)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• modelcontextprotocol.io
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Review compliance of the authorization of requests with respect to the latest MCP gateway specification. Add tests.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.