Back to search
mcp-gateway-aws
MCP serverGitHub
Serverless multi-user MCP server on AWS with OIDC sign-in and per-user, KMS-encrypted credentials
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/xochitlavalos--mcp-gateway-aws)HTML
<a href="/listings/xochitlavalos--mcp-gateway-aws"><img src="/api/listings/xochitlavalos--mcp-gateway-aws/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 214 lines
- # mcp-gateway-aws
- A serverless, multi-user [Model Context Protocol](https://modelcontextprotocol.io) 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 |
- ## Architecture
- ```mermaid
- 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
- ```mermaid
- 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.
- ```bash
- 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](https://github.com/settings/personal-access-tokens/new) with read-only repository permissions (Contents, Issues, Pull requests, Metadata). Then, with an access token from your IdP in `$JWT`:
- ```bash
- 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**
- ```bash
- 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:
- ```json
- {
- "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`:
- ```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
- ```bash
- 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.