Summary

Add support for API key authentication via URL query parameters for upstream MCP servers that require this method (e.g., Tavily MCP).

This feature is disabled by default and requires explicit opt-in due to the inherent security risks of exposing API keys in URLs (CWE-598).

Motivation

Some MCP servers (such as Tavily) require API key authentication via URL query parameters rather than HTTP headers. The existing authentication mechanisms (Basic, Bearer, OAuth, Custom Headers) all work through HTTP headers, making it impossible to connect to these services without this feature.

Closes #1580

Changes

Database & Schema

• Add auth_query_params JSON column to gateways table (Alembic migration)
• Add auth_query_param_key and auth_query_param_value fields to GatewayCreate/Update schemas
• Add auth_query_param_key and auth_query_param_value_masked fields to GatewayRead schema
• Add Pydantic validators for feature flag and host allowlist enforcement

Configuration

• Add INSECURE_ALLOW_QUERYPARAM_AUTH feature flag (default: false)
• Add INSECURE_QUERYPARAM_AUTH_ALLOWED_HOSTS allowlist (default: [])
• Update .env.example with documentation
• Update Helm chart values.yaml

Services

• GatewayService: Handle query_param auth in register/update, apply to SSE/StreamableHTTP connections
• ToolService: Decrypt and apply query params to URL during tool invocation
• ResourceService: Apply query params to URL during resource fetch
• ExportService: Include auth_query_params in gateway exports
• ImportService: Handle auth_query_params in gateway imports

Utilities

• Create mcpgateway/utils/url_auth.py with:
  • apply_query_param_auth(): Append decrypted auth params to URLs
  • sanitize_url_for_logging(): Redact sensitive params before logging
  • STATIC_SENSITIVE_PARAMS: FrozenSet of known sensitive parameter names

Admin UI

• Add "Query Parameter (INSECURE)" option to auth type dropdown
• Add security warning banner when selected
• Add input fields for parameter name and API key value
• Handle display of masked values when editing existing gateways

Documentation

• Add ADR-035: Query Parameter Authentication for Gateway Peers
• Add usage guide: docs/docs/using/query-param-auth.md
• Update README.md with new environment variables
• Update CLAUDE.md with Alembic migration guidance

Security Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Security Controls                           │
├─────────────────────────────────────────────────────────────────┤
│  Layer 1: Feature Flag (INSECURE_ALLOW_QUERYPARAM_AUTH)         │
│           └─ Disabled by default, requires explicit opt-in      │
├─────────────────────────────────────────────────────────────────┤
│  Layer 2: Host Allowlist (INSECURE_QUERYPARAM_AUTH_ALLOWED_HOSTS)│
│           └─ Empty = any host, Non-empty = strict allowlist     │
├─────────────────────────────────────────────────────────────────┤
│  Layer 3: Encrypted Storage (AUTH_ENCRYPTION_SECRET)            │
│           └─ API keys encrypted at rest in database             │
├─────────────────────────────────────────────────────────────────┤
│  Layer 4: Log Sanitization (sanitize_url_for_logging)           │
│           └─ Sensitive params redacted before any logging       │
├─────────────────────────────────────────────────────────────────┤
│  Layer 5: UI Warning                                            │
│           └─ Explicit security warning in Admin UI              │
└─────────────────────────────────────────────────────────────────┘

Example Usage

Enable the Feature

INSECURE_ALLOW_QUERYPARAM_AUTH=true
INSECURE_QUERYPARAM_AUTH_ALLOWED_HOSTS=["mcp.tavily.com"]

Register Tavily MCP

curl -X POST http://localhost:4444/admin/gateways \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tavily Search",
    "url": "https://mcp.tavily.com",
    "transport": "sse",
    "auth_type": "query_param",
    "auth_query_param_key": "tavilyApiKey",
    "auth_query_param_value": "tvly-your-api-key"
  }'

Testing

• Unit tests for url_auth.py (19 tests)
• All existing tests pass (5182 passed)
• make pylint passes (10.00/10)
• make flake8 passes
• make bandit passes
• Alembic migration verified (single head)

Checklist

• Code follows project conventions
• Tests added for new functionality
• Documentation updated (README, ADR, usage guide)
• Environment variables documented in .env.example
• Helm chart updated
• Security implications documented
• Commits signed (DCO)