Skip to main content
Glama
github-gateway

github-gateway

mcp-gateway-aws

A serverless, multi-user Model Context Protocol server on AWS. Each user gets read-only access to an upstream API with their own credential, never a shared service token. GitHub is the example upstream.

  • Auth: API Gateway HTTP API with a JWT authorizer. Any OIDC provider works (Okta, Auth0, Cognito, Entra ID).

  • Credentials: each user's GitHub token is envelope-encrypted with a customer-managed KMS key and bound to that user through the KMS encryption context.

  • Protocol: MCP Streamable HTTP in stateless JSON mode, implemented by hand over JSON-RPC 2.0 with no SDK dependency.

  • Infra: one TypeScript CDK stack. Least-privilege IAM is enforced by tests.

54 tests (45 pytest, 9 CDK assertions). No runtime dependencies beyond the Python standard library and the boto3 that ships with Lambda.

Why per-user credentials

The quick way to put an internal API behind an AI assistant is a single service token on the server. That works for a demo and breaks down in production:

Shared service token

Per-user credential (this repo)

Everyone sees whatever the service account can see

Users see exactly what their own account can see

Audit logs show one identity for all activity

Upstream audit logs show the real user

One leaked token exposes everything

A leaked row is useless without KMS and the matching user context

Off-boarding means rotating a token everyone uses

Delete one row, or let it expire

Rate limits are shared by all users

Rate limits are per user

Related MCP server: GitHub MCP

Architecture

flowchart LR
    subgraph Client
        C[Claude Code / Claude Desktop<br/>or any MCP client]
    end
    IdP[(OIDC provider)]
    subgraph AWS
        API[API Gateway HTTP API<br/>JWT authorizer, throttling]
        M[MCP handler Lambda<br/>kms:Decrypt only]
        K[Connect handler Lambda<br/>kms:Encrypt only]
        T[(DynamoDB<br/>user_sub -> ciphertext<br/>TTL, PITR, SSE)]
        KMS[[KMS CMK<br/>rotation on]]
    end
    GH[GitHub REST API]

    C -- "Bearer JWT" --> API
    C -. "sign in" .-> IdP
    API -- "POST/GET/DELETE /mcp" --> M
    API -- "/connect, /connect/status" --> K
    K -- "Encrypt(ctx: user_sub)" --> KMS
    K --> T
    M --> T
    M -- "Decrypt(ctx: user_sub)" --> KMS
    M -- "GET only, user's token" --> GH
    K -- "GET /user (validate)" --> GH

Request flow

sequenceDiagram
    autonumber
    participant U as User
    participant C as MCP client
    participant G as API Gateway (JWT)
    participant K as Connect Lambda
    participant M as MCP Lambda
    participant D as DynamoDB
    participant KMS
    participant GH as GitHub

    Note over U,GH: One-time: connect a read-only GitHub token
    U->>G: POST /connect {token} + Bearer JWT
    G->>K: verified claims (sub)
    K->>GH: GET /user (is the token valid? any write scopes?)
    K->>KMS: Encrypt(token, context = {user_sub: sub})
    K->>D: PutItem(sub, ciphertext, expires_at)

    Note over U,GH: Every MCP request
    C->>G: POST /mcp tools/call + Bearer JWT
    G->>M: verified claims (sub)
    M->>D: GetItem(sub)
    M->>KMS: Decrypt(ciphertext, context = {user_sub: sub})
    M->>GH: GET with the user's own token
    GH-->>M: data visible to that user only
    M-->>C: JSON-RPC result (isError on upstream failure)

Tools

All tools are annotated readOnlyHint: true, and the GitHub client can only send GET requests.

Tool

What it does

list_repos

Repositories the user can access, most recently updated first

get_file

Read a text file (up to 200 KB) or list a directory

search_issues

GitHub issue and PR search, e.g. repo:octo/app is:open label:bug

list_pull_requests

Pull requests in a repository, by state

Each tool's JSON Schema is advertised in tools/list and enforced before any upstream call, so bad arguments never reach GitHub.

Deploy

Prerequisites: Node 20+, Python 3.12, AWS CDK v2, an AWS account you control, and an OIDC provider that issues access tokens for an API audience.

cd cdk
npm ci
npx cdk bootstrap   # once per account and region
npx cdk deploy \
  -c oidcIssuer=https://idp.example.com/oauth2/default \
  -c oidcAudience=api://mcp-gateway \
  -c tokenTtlDays=90

Outputs include McpUrl and ConnectUrl.

Connect your GitHub token

Create a fine-grained personal access token with read-only repository permissions (Contents, Issues, Pull requests, Metadata). Then, with an access token from your IdP in $JWT:

curl -X POST "$CONNECT_URL" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"token": "github_pat_..."}'

curl "$CONNECT_URL/status" -H "Authorization: Bearer $JWT"
curl -X DELETE "$CONNECT_URL" -H "Authorization: Bearer $JWT"   # revoke

Classic tokens with write scopes (repo, workflow, write:*, admin:*, ...) are rejected.

Use it from an MCP client

Claude Code

claude mcp add --transport http github-gateway "$MCP_URL" \
  --header "Authorization: Bearer $JWT"

Or check a project-scoped .mcp.json into a repo, so the token comes from each developer's environment:

{
  "mcpServers": {
    "github-gateway": {
      "type": "http",
      "url": "https://abc123.execute-api.us-east-1.amazonaws.com/mcp",
      "headers": { "Authorization": "Bearer ${MCP_GATEWAY_JWT}" }
    }
  }
}

Claude Desktop (through the mcp-remote bridge), in claude_desktop_config.json:

{
  "mcpServers": {
    "github-gateway": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://abc123.execute-api.us-east-1.amazonaws.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer <your access token>" }
    }
  }
}

Security model

Threat

Control

Unauthenticated access

JWT authorizer on every route (asserted in CDK tests); handlers also fail closed if claims are missing

One user reading another user's token

Ciphertext is bound to {user_sub} via KMS encryption context; a row copied to another key will not decrypt (unit tested)

Over-broad Lambda permissions

MCP Lambda: kms:Decrypt + dynamodb:GetItem only. Connect Lambda: kms:Encrypt + Get/Put/Delete only. Both KMS grants require the encryption context key. No wildcard actions (tested)

Tokens leaking into logs

Tokens and request bodies are never logged; user IDs are logged as a truncated SHA-256; GitHubClient.__repr__ masks the token; tests assert neither token nor raw sub appears in logs

Write access through the gateway

Client issues GET only; tools are read-only; classic tokens with write scopes are rejected at connect time

Stale credentials

DynamoDB TTL plus an application-side expiry check (TTL deletion is lazy)

Abuse and runaway agents

Stage throttling (20 rps, burst 40); upstream rate limits are per user

Data loss

PITR on the table, key and table retained on stack deletion, KMS rotation on

Path traversal and injection in tool args

Schema validation with patterns for owner and repo; . and .. path segments rejected; paths URL-encoded

Design decisions

  • Stateless Streamable HTTP, no SSE. Lambda has no long-lived connections, and tools-only servers do not need server-initiated messages. Each POST returns one JSON response, notifications return 202, and GET /mcp returns 405 as the spec allows.

  • Hand-rolled JSON-RPC. The protocol surface for a tools server is small. Writing it directly keeps the deployment package tiny, cold starts fast, and the error mapping explicit: protocol errors are JSON-RPC errors, while tool failures are isError results the model can read and recover from.

  • Lazy credential access. initialize, ping, and tools/list never touch DynamoDB or KMS. The token is decrypted only for tools/call, once per request, and never cached across invocations.

  • Two encryption layers, two purposes. The table uses AWS-managed encryption at rest. The token itself is envelope-encrypted with a separate CMK so that only the two Lambdas, under narrow conditions, can ever see plaintext. Using the CMK for the table too would force broad decrypt grants on it.

  • Separate Lambdas for read and write paths. The function that serves model traffic cannot write credentials, and the function that writes credentials cannot decrypt them.

Testing

python -m venv .venv && . .venv/bin/activate
pip install -r requirements-dev.txt
pytest                      # 45 tests: protocol, tools, connect flow, token store

cd cdk && npm ci && npm test   # 9 CDK assertion tests: encryption, auth, IAM

The Python tests use in-memory fakes for KMS (including encryption-context enforcement), DynamoDB, and the GitHub HTTP API, so they run offline in well under a second.

Roadmap

  • Implement the MCP authorization spec (OAuth 2.0 protected resource metadata) so clients can sign in through the browser instead of pasting a JWT.

  • GitHub App user-to-server tokens instead of personal access tokens.

  • Pluggable upstreams behind the same connect and tool interfaces.

  • WAF and per-user quotas in DynamoDB.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables self-hosted, read-only remote interaction with GitHub repositories, allowing listing repositories, searching code, and inspecting commits, pull requests, issues, and diffs via authenticated MCP clients.
      MIT