API Gateway Deployment

Multi-provider API gateway deployment guide covering Kong, AWS, GCP, Azure, and Kubernetes ingress

API Gateway Deployment Guide

Complete guide for deploying OpenAPI-compliant APIs to production API Gateways.

Table of Contents

1. Prerequisites
2. Kong API Gateway
3. AWS API Gateway
4. Google Cloud API Gateway
5. Azure API Management
6. Kubernetes Ingress

---

Prerequisites

OpenAPI Specification

• File: openapi/v1.json
• Version: OpenAPI 3.1.0
• Endpoints: 22
• Schemas: 42

Required Configuration

• JWT secret key
• Keycloak SSO (optional)
• OpenFGA authorization
• PostgreSQL database (for GDPR storage)
• Redis (for rate limiting)

---

Kong API Gateway

1. Install Kong Gateway

# Using Docker
docker run -d --name kong-gateway \
  --network=kong-net \
  -e "KONG_DATABASE=postgres" \
  -e "KONG_PG_HOST=postgres" \
  -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
  -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
  -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
  -e "KONG_ADMIN_LISTEN=0.0.0.0:8001" \
  -p 8000:8000 \
  -p 8443:8443 \
  -p 8001:8001 \
  kong:latest

2. Import OpenAPI Specification

# Install deck (Kong's declarative configuration tool)
brew install deck

# Convert OpenAPI to Kong config
deck file openapi2kong \
  -s openapi/v1.json \
  -o kong.yaml

# Apply configuration
deck gateway sync kong.yaml

3. Configure API Key Plugin

Kong configuration is already integrated:

• See src/mcp_server_langgraph/api/api_keys.py:validate endpoint
• Kong calls /api/v1/api-keys/validate to exchange API key for JWT

Kong Plugin Config:

plugins:
  - name: request-transformer
    config:
      add:
        headers:
          - "Authorization: Bearer {{jwt_token}}"

4. Enable Rate Limiting

curl -X POST http://localhost:8001/services/mcp-server/plugins \
  --data "name=rate-limiting" \
  --data "config.minute=60" \
  --data "config.policy=redis" \
  --data "config.redis_host=redis"

---

AWS API Gateway

1. Import OpenAPI Spec

# Using AWS CLI
aws apigateway import-rest-api \
  --body file://openapi/v1.json \
  --fail-on-warnings \
  --endpoint-configuration types=REGIONAL

# Save API ID
export API_ID=<api-id-from-output>

2. Configure JWT Authorizer

# Create Lambda authorizer for JWT validation
aws apigateway create-authorizer \
  --rest-api-id $API_ID \
  --name JWTAuthorizer \
  --type TOKEN \
  --authorizer-uri arn:aws:apigateway:region:lambda:path/2015-03-31/functions/arn:aws:lambda:region:account-id:function:jwt-authorizer/invocations \
  --identity-source method.request.header.Authorization

3. Deploy to Stage

# Create deployment
aws apigateway create-deployment \
  --rest-api-id $API_ID \
  --stage-name production

# Get invoke URL
echo "https://${API_ID}.execute-api.region.amazonaws.com/production"

4. Add Usage Plan (Rate Limiting)

# Create usage plan
aws apigateway create-usage-plan \
  --name "Production Tier" \
  --throttle burstLimit=100,rateLimit=50 \
  --quota limit=10000,period=DAY

# Associate with API stage
aws apigateway create-usage-plan-key \
  --usage-plan-id $USAGE_PLAN_ID \
  --key-type API_KEY \
  --key-id $API_KEY_ID

---

Google Cloud API Gateway

1. Create API Config

# Deploy OpenAPI spec
gcloud api-gateway api-configs create mcp-api-v1 \
  --api=mcp-server \
  --openapi-spec=openapi/v1.json \
  --project=$PROJECT_ID \
  --backend-auth-service-account=$SERVICE_ACCOUNT

2. Create Gateway

# Create gateway
gcloud api-gateway gateways create mcp-gateway \
  --api=mcp-server \
  --api-config=mcp-api-v1 \
  --location=us-central1 \
  --project=$PROJECT_ID

# Get gateway URL
gcloud api-gateway gateways describe mcp-gateway \
  --location=us-central1 \
  --format="value(defaultHostname)"

3. Configure Authentication

Option A: API Keys

# Add to openapi/v1.json
securityDefinitions:
  api_key:
    type: apiKey
    name: x-api-key
    in: header

security:
  - api_key: []

Option B: JWT (Firebase Auth)

securityDefinitions:
  firebase:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://securetoken.google.com/PROJECT_ID"
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/[e-mail]"
    x-google-audiences: "PROJECT_ID"

---

Azure API Management

1. Import OpenAPI

# Create API Management instance
az apim create \
  --name mcp-apim \
  --resource-group mcp-resources \
  --publisher-email [e-mail] \
  --publisher-name "MCP API"

# Import OpenAPI spec
az apim api import \
  --resource-group mcp-resources \
  --service-name mcp-apim \
  --path /api/v1 \
  --specification-format OpenApi \
  --specification-path openapi/v1.json \
  --api-id mcp-server-api

2. Configure JWT Validation

<!-- Add to inbound policy -->
<validate-jwt header-name="Authorization" failed-validation-httpcode="401">
  <openid-config url="https://YOUR_KEYCLOAK/realms/YOUR_REALM/.well-known/openid-configuration" />
  <required-claims>
    <claim name="aud" match="any">
      <value>mcp-api</value>
    </claim>
  </required-claims>
</validate-jwt>

3. Enable Rate Limiting

<rate-limit calls="100" renewal-period="60" />
<quota calls="10000" renewal-period="86400" />

---

Kubernetes Ingress (NGINX/Traefik)

Option 1: NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mcp-api-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/rate-limit: "100"
    nginx.ingress.kubernetes.io/cors-allow-origin: "*"
    nginx.ingress.kubernetes.io/auth-url: "http://mcp-server.default.svc.cluster.local:8000/auth/validate"
spec:
  ingressClassName: nginx
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api/v1
            pathType: Prefix
            backend:
              service:
                name: mcp-server
                port:
                  number: 8000
  tls:
    - hosts:
        - api.example.com
      secretName: api-tls-cert

Option 2: Traefik Ingress

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: mcp-api-route
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`api.example.com`) && PathPrefix(`/api/v1`)
      kind: Rule
      services:
        - name: mcp-server
          port: 8000
      middlewares:
        - name: rate-limit
        - name: jwt-auth
  tls:
    certResolver: letsencrypt

---

Environment Configuration

Required Environment Variables

# JWT Authentication
export JWT_SECRET_KEY="your-secret-key-here"

# Keycloak SSO
export KEYCLOAK_SERVER_URL="https://keycloak.example.com"
export KEYCLOAK_REALM="mcp-realm"
export KEYCLOAK_CLIENT_ID="mcp-api"
export KEYCLOAK_CLIENT_SECRET="client-secret"

# OpenFGA Authorization
export OPENFGA_API_URL="https://openfga.example.com"
export OPENFGA_STORE_ID="your-store-id"
export OPENFGA_API_TOKEN="openfga-token"

# Database
export DATABASE_URL="postgresql://user:pass@postgres:5432/mcp"

# Redis (Rate Limiting)
export REDIS_URL="redis://redis:6379/0"

# GDPR Storage
export GDPR_STORAGE_BACKEND="postgres"

# CORS
export CORS_ORIGINS="https://app.example.com,https://admin.example.com"

---

Testing Deployment

1. Health Check

curl https://api.example.com/health
# Expected: {"status": "healthy"}

curl https://api.example.com/health/ready
# Expected: {"status": "ready", "checks": {...}}

2. OpenAPI Documentation

# Swagger UI
https://api.example.com/docs

# ReDoc
https://api.example.com/redoc

# OpenAPI JSON
https://api.example.com/openapi.json

3. Authentication Test

# Login
curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "secret"
  }'

# Use JWT token
export TOKEN="<access_token from response>"

curl https://api.example.com/api/v1/api-keys/ \
  -H "Authorization: Bearer $TOKEN"

4. Rate Limiting Test

# Make 101 requests (rate limit is 100/minute)
for i in {1..101}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    https://api.example.com/api/version
done

# Should see 200 responses, then 429 (Too Many Requests)

---

Monitoring & Observability

Prometheus Metrics

# Endpoint: /metrics/prometheus

# Metrics exposed:
# - http_requests_total
# - http_request_duration_seconds
# - circuit_breaker_state
# - rate_limit_exceeded_total

Grafana Dashboard

# Import dashboard from grafana.com
# ID: 14282 (FastAPI dashboard)

# Configure Prometheus data source
# URL: http://prometheus:9090

Traces (OpenTelemetry)

# Export to Jaeger
export OTEL_EXPORTER_OTLP_ENDPOINT="http://jaeger:4318"
export OTEL_SERVICE_NAME="mcp-server"

---

Security Checklist

Before production deployment:

• JWT secret is secure (32+ characters, rotated)
• HTTPS/TLS enabled (valid certificates)
• CORS origins restricted (not *)
• Rate limiting configured (per user/IP)
• OpenFGA authorization policies defined
• Database credentials secured (secrets manager)
• API keys hashed with bcrypt
• GDPR storage uses PostgreSQL (not in-memory)
• Audit logging enabled
• Circuit breakers configured
• Health checks responding
• Monitoring alerts configured

---

API Gateway Features Comparison

Feature	Kong	AWS	GCP	Azure	NGINX
OpenAPI Import	✅	✅	✅	✅	⚠️
JWT Validation	✅	✅	✅	✅	✅
Rate Limiting	✅	✅	✅	✅	✅
API Key Management	✅	✅	✅	✅	❌
SCIM Support	✅	⚠️	⚠️	✅	❌
Monitoring	✅	✅	✅	✅	⚠️
Auto-scaling	✅	✅	✅	✅	⚠️

Legend: ✅ Full Support | ⚠️ Partial | ❌ Not Supported

---

Production Deployment Example (Kong + Kubernetes)

Complete Setup

# mcp-deployment.yaml
apiVersion: v1
kind: Service
metadata:
  name: mcp-server
spec:
  selector:
    app: mcp-server
  ports:
    - port: 8000
      targetPort: 8000
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-server
  template:
    metadata:
      labels:
        app: mcp-server
    spec:
      containers:
        - name: mcp-server
          image: your-registry/mcp-server:2.8.0
          ports:
            - containerPort: 8000
          env:
            - name: JWT_SECRET_KEY
              valueFrom:
                secretKeyRef:
                  name: mcp-secrets
                  key: jwt-secret
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: mcp-secrets
                  key: database-url
          livenessProbe:
            httpGet:
              path: /health
              port: 8000
            initialDelaySeconds: 10
            periodSeconds: 30
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 8000
            initialDelaySeconds: 5
            periodSeconds: 10
---
# Kong Ingress
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: rate-limiting
config:
  minute: 100
  policy: redis
  redis_host: redis
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mcp-api
  annotations:
    konghq.com/plugins: rate-limiting
spec:
  ingressClassName: kong
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: kong-proxy
                port:
                  number: 80

---

API Versioning Strategy

URL-Based Versioning (Current)

• /api/v1/* - Version 1 (current)
• /api/v2/* - Version 2 (future)

Header-Based Versioning (Optional)

curl https://api.example.com/api/v1/users/me/data \
  -H "X-API-Version: 1.0" \
  -H "Authorization: Bearer $TOKEN"

Deprecation Policy

1. Announce deprecation - 6 months notice
2. Mark as deprecated - Add deprecated: true to OpenAPI
3. Update /api/version - Add to deprecated_versions with sunset date
4. Return headers - Sunset: Sat, 01 Jun 2026 00:00:00 GMT
5. Remove version - After sunset date

---

Breaking Change Prevention

Automated Validation

# Run before deploying
python scripts/validation/validate_openapi.py

# Check for breaking changes
python scripts/validation/detect_breaking_changes.py \
  --baseline openapi/v1-baseline.json \
  --current openapi/v1.json

Breaking Changes (Require Version Bump)

• ❌ Removing endpoints
• ❌ Removing required fields
• ❌ Changing field types
• ❌ Renaming fields
• ❌ Changing authentication methods

Safe Changes (No Version Bump)

• ✅ Adding new endpoints
• ✅ Adding optional fields
• ✅ Adding new response fields
• ✅ Adding query parameters (optional)
• ✅ Expanding enum values

---

CI/CD Integration

GitHub Actions

# .github/workflows/api-deploy.yml
name: Deploy API

on:
  push:
    branches: [main]

jobs:
  validate-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate OpenAPI Spec
        run: |
          python scripts/validation/validate_openapi.py

      - name: Detect Breaking Changes
        run: |
          python scripts/validation/detect_breaking_changes.py \
            --baseline openapi/v1-baseline.json \
            --current openapi/v1.json

  generate-sdks:
    needs: validate-openapi
    runs-on: ubuntu-latest
    steps:
      - name: Generate Python SDK
        run: |
          docker run --rm \
            -v $(pwd):/local \
            openapitools/openapi-generator-cli generate \
            -i /local/openapi/v1.json \
            -g python \
            -o /local/clients/python

      - name: Publish to PyPI
        run: |
          cd clients/python
          python -m build
          twine upload dist/*

  deploy-to-kong:
    needs: validate-openapi
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Kong
        run: |
          deck file openapi2kong -s openapi/v1.json -o kong.yaml
          deck gateway sync kong.yaml --kong-addr https://kong-admin.example.com

---

Troubleshooting

Issue: 404 on API Endpoints

Cause: Routers not registered Solution: Verify all routers in server_streamable.py:1262-1271

Issue: OpenAPI Generation Fails

Cause: Pydantic model issues ($ref conflicts) Solution: See scim/schema.py:68-77 for $ref workaround

Issue: Authentication Fails

Cause: JWT secret not configured Solution: Set JWT_SECRET_KEY environment variable

Issue: GDPR Operations Fail

Cause: In-memory storage in production Solution: Set GDPR_STORAGE_BACKEND=postgres

Issue: Rate Limiting Not Working

Cause: Redis not configured Solution: Set REDIS_URL and configure SlowAPI

---

Performance Tuning

Recommended Settings

# Gunicorn workers
workers = (2 * cpu_cores) + 1  # e.g., 9 workers for 4 cores

# Worker class
worker_class = "uvicorn.workers.UvicornWorker"

# Connection limits
max_requests = 10000  # Restart workers after N requests
max_requests_jitter = 1000  # Add randomness to prevent thundering herd
keepalive = 65  # Seconds

# Timeouts
timeout = 120  # Request timeout
graceful_timeout = 30  # Graceful shutdown

Database Connection Pooling

# asyncpg pool settings
min_size = 10
max_size = 50
max_queries = 50000
max_inactive_connection_lifetime = 300

---

Support & Resources

• OpenAPI Spec: openapi/v1.json
• MCP Tools Spec: openapi/mcp-tools.json
• API Documentation: /docs (Swagger UI)
• Compliance Report: docs/api-compliance-report.mdx
• SDK Usage: clients/README.md

Generated: 2025-11-02 Version: 2.8.0