API密钥生命周期管理服务

curl -O https://raw.githubusercontent.com/gatesuite/mcpgate/main/docker-compose.yml
export ADMIN_API_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")
docker compose up -d

curl http://localhost:8000/health
# {"status": "ok", "service": "mcpgate"}

export MCPGATE_VERSION=1.2.3
docker compose up -d

git clone https://github.com/gatesuite/mcpgate.git
cd mcpgate

# 1. Create your env file
cp .env.example .env
# Edit .env — set a strong ADMIN_API_KEY

# 2. Start the stack (builds from local Dockerfile)
make app-up

# Prerequisites: Python 3.12+, PostgreSQL
pip install -r requirements.txt

export DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mcpgate
export ADMIN_API_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")

uvicorn app.main:app --host 0.0.0.0 --port 8000

python3 -c "import secrets; print(secrets.token_hex(32))"

User        Your App (backend)       MCPGate         MCP Server
 │                  │                    │                 │
 │── signup ───────▶│                    │                 │
 │                  │── POST /keys ─────▶│                 │
 │                  │◀─ {key: mcp_sk_…} ─│                 │
 │◀── key ──────────│                    │                 │
 │                  │                    │                 │
 │── MCP request ───────────────────────────────────────── ▶│
 │                  │                    │◀─ POST /verify ─│
 │                  │                    │── {valid:true} ▶│
 │◀── response ─────────────────────────────────────────────│

import httpx

async def create_mcp_key(user_id: str, name: str) -> str:
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "http://mcpgate:8000/api/v1/keys",
            headers={"Authorization": f"Bearer {ADMIN_API_KEY}"},
            json={
                "user_id": user_id,
                "name": name,
                "scopes": {"read": True, "write": True},
                "expires_in_days": 365,
            },
        )
        return resp.json()["key"]   # mcp_sk_... — return to user, never store

async def verify_mcp_key(key: str) -> dict | None:
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "http://mcpgate:8000/api/v1/verify",
            json={"key": key},
        )
        data = resp.json()
        return data if data["valid"] else None

async function verifyMcpKey(key: string) {
  const resp = await fetch("http://mcpgate:8000/api/v1/verify", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ key }),
  });
  const data = await resp.json();
  return data.valid ? { userId: data.user_id, scopes: data.scopes } : null;
}

async def handle_mcp_request(key: str, tool: str):
    auth = await verify_mcp_key(key)
    if auth is None:
        raise Unauthorized("Invalid API key")

    scopes = auth.get("scopes") or {}
    if tool in ("write_file", "execute_code") and not scopes.get("write"):
        raise Forbidden("Key does not have write scope")

    # proceed...

curl -X DELETE http://mcpgate:8000/api/v1/keys/{key_id} \
  -H "Authorization: Bearer $ADMIN_API_KEY"

curl -X POST http://localhost:8000/api/v1/keys \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_12345",
    "name": "Claude Desktop",
    "scopes": {"read": true, "write": false},
    "expires_in_days": 365
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "key": "mcp_sk_3f8a1c2e9b4d7f6a_4a7b2c9e...",
  "prefix": "mcp_sk_3f8a1c2e9b4d7f6a_...9b",
  "user_id": "usr_12345",
  "name": "Claude Desktop",
  "created_at": "2026-04-16T10:00:00Z"
}

curl -X POST http://localhost:8000/api/v1/verify \
  -H "Content-Type: application/json" \
  -d '{"key": "mcp_sk_3f8a1c2e9b4d7f6a_4a7b2c9e..."}'

{
  "valid": true,
  "user_id": "usr_12345",
  "scopes": {"read": true, "write": false},
  "error": null
}

{ "valid": false, "user_id": null, "scopes": null, "error": "Invalid API key" }

curl http://localhost:8000/api/v1/keys/usr_12345 \
  -H "Authorization: Bearer $ADMIN_API_KEY"

curl -X DELETE http://localhost:8000/api/v1/keys/{key_id} \
  -H "Authorization: Bearer $ADMIN_API_KEY"

-- List expired keys
SELECT id, user_id, prefix, expires_at
FROM api_keys
WHERE expires_at < NOW();

-- Bulk delete expired keys older than 30 days
DELETE FROM api_keys
WHERE expires_at < NOW() - INTERVAL '30 days';

-- Keys never used
SELECT id, user_id, prefix, created_at
FROM api_keys
WHERE last_used_at IS NULL
  AND created_at < NOW() - INTERVAL '30 days';

-- Keys unused in the last 90 days
SELECT id, user_id, prefix, last_used_at
FROM api_keys
WHERE last_used_at < NOW() - INTERVAL '90 days';

# 1. Create a replacement
new_key = await create_mcp_key(user_id="usr_12345", name="Claude Desktop (rotated)")

# 2. Deliver new_key to the user

# 3. Delete the old key (fetch its ID via GET /keys/{user_id} first)
await client.delete(f"http://mcpgate:8000/api/v1/keys/{old_key_id}",
                    headers={"Authorization": f"Bearer {ADMIN_API_KEY}"})

make app-up     # builds production image, starts MCPGate + Postgres
make app-logs   # tail logs
make app-down   # stop (volumes preserved)

kubectl create secret generic mcpgate-secrets \
  --from-literal=DATABASE_URL="postgresql+asyncpg://user:pass@host:5432/mcpgate" \
  --from-literal=ADMIN_API_KEY="$(openssl rand -hex 32)"

helm install mcpgate oci://ghcr.io/gatesuite/charts/mcpgate \
  --set existingSecret=mcpgate-secrets

helm install mcpgate oci://ghcr.io/gatesuite/charts/mcpgate -f my-values.yaml

helm install mcpgate ./deployments/helm/mcpgate -f my-values.yaml

apiVersion: v1
kind: Secret
metadata:
  name: mcpgate-secrets
type: Opaque
stringData:
  DATABASE_URL: postgresql+asyncpg://user:pass@postgres:5432/mcpgate
  ADMIN_API_KEY: your-strong-secret-here
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcpgate
spec:
  replicas: 2
  selector:
    matchLabels: { app: mcpgate }
  template:
    metadata:
      labels: { app: mcpgate }
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 1000
      containers:
        - name: mcpgate
          image: ghcr.io/gatesuite/mcpgate:latest
          ports:
            - containerPort: 8000
          envFrom:
            - secretRef:
                name: mcpgate-secrets
          livenessProbe:
            httpGet: { path: /health, port: 8000 }
          readinessProbe:
            httpGet: { path: /health, port: 8000 }
          resources:
            requests: { cpu: 50m, memory: 64Mi }
            limits:   { cpu: 250m, memory: 128Mi }
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop: [ALL]
---
apiVersion: v1
kind: Service
metadata:
  name: mcpgate
spec:
  selector: { app: mcpgate }
  ports:
    - port: 8000
      targetPort: 8000

graph TB
    Backend["🖥️ Your Backend"]
    MCPServer["🤖 Your MCP Server"]

    subgraph EKS Cluster
        subgraph Private["Private (ClusterIP Services)"]
            MG["MCPGate<br/>ClusterIP :8000"]
            PG["PostgreSQL<br/>ClusterIP :5432"]
        end
    end

    Backend -->|"Admin API<br/>(create/list/revoke)"| MG
    MCPServer -->|"Verify on every request<br/>POST /verify"| MG
    MG -->|"Async"| PG

    style MG fill:#10b981,stroke:#047857,color:#fff
    style PG fill:#6366f1,stroke:#4338ca,color:#fff
    style Backend fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style MCPServer fill:#f59e0b,stroke:#d97706,color:#fff

sequenceDiagram
    actor User
    participant Client as MCP Client (Claude Desktop, etc.)
    participant MCP as Your MCP Server
    participant MG as MCPGate
    participant DB as PostgreSQL

    User->>Client: Use MCP tool
    Client->>MCP: Request with API key header
    MCP->>MG: POST /api/v1/verify { key: "mcp_sk_..." }
    MG->>MG: Extract public_id from key
    MG->>DB: SELECT WHERE public_id = ? AND is_active = true
    DB-->>MG: Return key record
    MG->>MG: bcrypt.checkpw(sha256(key), stored_hash)
    MG->>MG: Check expires_at
    MG->>DB: UPDATE last_used_at = now()
    MG-->>MCP: { valid: true, user_id, scopes }
    MCP->>MCP: Check scopes, enforce permissions
    MCP-->>Client: Tool result
    Client-->>User: Display result

mcpgate/
├── app/
│   ├── main.py              # FastAPI entrypoint, lifespan, CORS
│   ├── api/
│   │   └── routes.py        # All 5 endpoints: create, list, delete, verify, health
│   ├── core/
│   │   ├── config.py        # Settings via pydantic-settings + .env
│   │   ├── database.py      # Async SQLAlchemy engine + session factory
│   │   └── security.py      # Key generation, SHA-256 pre-hash, bcrypt hash/verify
│   ├── models/
│   │   └── api_key.py       # ApiKey SQLAlchemy ORM model
│   └── schemas/
│       └── api_key.py       # Pydantic request/response schemas
├── tests/
│   ├── conftest.py          # Fixtures: client, admin_headers, DB setup/teardown
│   ├── test_health.py       # Health endpoint
│   ├── test_keys.py         # Create, list, revoke (with/without auth)
│   └── test_verify.py       # Valid, invalid, expired, revoked, tampered keys
├── deployments/
│   ├── docker-compose/      # Dev compose (builds from local Dockerfile)
│   └── helm/mcpgate/        # Kubernetes Helm chart
├── docs/                    # Astro/Starlight documentation site
├── .github/workflows/       # CI/CD: release-please, e2e, docker-publish, docs
├── Dockerfile               # Multi-stage: production + test targets
├── docker-compose.yml       # End-user zero-config deploy (pulls from GHCR)
├── docker-compose.test.yml  # Test runner (make test-run)
└── Makefile                 # app-*, docs-*, test-* targets