Skip to content
Back to search

mcp-gateway-aws

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xochitlavalos--mcp-gateway-aws/badge.svg)](/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
  1. # mcp-gateway-aws
  2. 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.
  3. - **Auth:** API Gateway HTTP API with a JWT authorizer. Any OIDC provider works (Okta, Auth0, Cognito, Entra ID).
  4. - **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.
  5. - **Protocol:** MCP Streamable HTTP in stateless JSON mode, implemented by hand over JSON-RPC 2.0 with no SDK dependency.
  6. - **Infra:** one TypeScript CDK stack. Least-privilege IAM is enforced by tests.
  7. 54 tests (45 pytest, 9 CDK assertions). No runtime dependencies beyond the Python standard library and the boto3 that ships with Lambda.
  8. ## Why per-user credentials
  9. 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:
  10. | Shared service token | Per-user credential (this repo) |
  11. |---|---|
  12. | Everyone sees whatever the service account can see | Users see exactly what their own account can see |
  13. | Audit logs show one identity for all activity | Upstream audit logs show the real user |
  14. | One leaked token exposes everything | A leaked row is useless without KMS and the matching user context |
  15. | Off-boarding means rotating a token everyone uses | Delete one row, or let it expire |
  16. | Rate limits are shared by all users | Rate limits are per user |
  17. ## Architecture
  18. ```mermaid
  19. flowchart LR
  20. subgraph Client
  21. C[Claude Code / Claude Desktop<br/>or any MCP client]
  22. end
  23. IdP[(OIDC provider)]
  24. subgraph AWS
  25. API[API Gateway HTTP API<br/>JWT authorizer, throttling]
  26. M[MCP handler Lambda<br/>kms:Decrypt only]
  27. K[Connect handler Lambda<br/>kms:Encrypt only]
  28. T[(DynamoDB<br/>user_sub -> ciphertext<br/>TTL, PITR, SSE)]
  29. KMS[[KMS CMK<br/>rotation on]]
  30. end
  31. GH[GitHub REST API]
  32. C -- "Bearer JWT" --> API
  33. C -. "sign in" .-> IdP
  34. API -- "POST/GET/DELETE /mcp" --> M
  35. API -- "/connect, /connect/status" --> K
  36. K -- "Encrypt(ctx: user_sub)" --> KMS
  37. K --> T
  38. M --> T
  39. M -- "Decrypt(ctx: user_sub)" --> KMS
  40. M -- "GET only, user's token" --> GH
  41. K -- "GET /user (validate)" --> GH
  42. ```
  43. ### Request flow
  44. ```mermaid
  45. sequenceDiagram
  46. autonumber
  47. participant U as User
  48. participant C as MCP client
  49. participant G as API Gateway (JWT)
  50. participant K as Connect Lambda
  51. participant M as MCP Lambda
  52. participant D as DynamoDB
  53. participant KMS
  54. participant GH as GitHub
  55. Note over U,GH: One-time: connect a read-only GitHub token
  56. U->>G: POST /connect {token} + Bearer JWT
  57. G->>K: verified claims (sub)
  58. K->>GH: GET /user (is the token valid? any write scopes?)
  59. K->>KMS: Encrypt(token, context = {user_sub: sub})
  60. K->>D: PutItem(sub, ciphertext, expires_at)
  61. Note over U,GH: Every MCP request
  62. C->>G: POST /mcp tools/call + Bearer JWT
  63. G->>M: verified claims (sub)
  64. M->>D: GetItem(sub)
  65. M->>KMS: Decrypt(ciphertext, context = {user_sub: sub})
  66. M->>GH: GET with the user's own token
  67. GH-->>M: data visible to that user only
  68. M-->>C: JSON-RPC result (isError on upstream failure)
  69. ```
  70. ## Tools
  71. All tools are annotated `readOnlyHint: true`, and the GitHub client can only send `GET` requests.
  72. | Tool | What it does |
  73. |---|---|
  74. | `list_repos` | Repositories the user can access, most recently updated first |
  75. | `get_file` | Read a text file (up to 200 KB) or list a directory |
  76. | `search_issues` | GitHub issue and PR search, e.g. `repo:octo/app is:open label:bug` |
  77. | `list_pull_requests` | Pull requests in a repository, by state |
  78. Each tool's JSON Schema is advertised in `tools/list` and enforced before any upstream call, so bad arguments never reach GitHub.
  79. ## Deploy
  80. 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.
  81. ```bash
  82. cd cdk
  83. npm ci
  84. npx cdk bootstrap # once per account and region
  85. npx cdk deploy \
  86. -c oidcIssuer=https://idp.example.com/oauth2/default \
  87. -c oidcAudience=api://mcp-gateway \
  88. -c tokenTtlDays=90
  89. ```
  90. Outputs include `McpUrl` and `ConnectUrl`.
  91. ### Connect your GitHub token
  92. 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`:
  93. ```bash
  94. curl -X POST "$CONNECT_URL" \
  95. -H "Authorization: Bearer $JWT" \
  96. -H "Content-Type: application/json" \
  97. -d '{"token": "github_pat_..."}'
  98. curl "$CONNECT_URL/status" -H "Authorization: Bearer $JWT"
  99. curl -X DELETE "$CONNECT_URL" -H "Authorization: Bearer $JWT" # revoke
  100. ```
  101. Classic tokens with write scopes (`repo`, `workflow`, `write:*`, `admin:*`, ...) are rejected.
  102. ## Use it from an MCP client
  103. **Claude Code**
  104. ```bash
  105. claude mcp add --transport http github-gateway "$MCP_URL" \
  106. --header "Authorization: Bearer $JWT"
  107. ```
  108. Or check a project-scoped `.mcp.json` into a repo, so the token comes from each developer's environment:
  109. ```json
  110. {
  111. "mcpServers": {
  112. "github-gateway": {
  113. "type": "http",
  114. "url": "https://abc123.execute-api.us-east-1.amazonaws.com/mcp",
  115. "headers": { "Authorization": "Bearer ${MCP_GATEWAY_JWT}" }
  116. }
  117. }
  118. }
  119. ```
  120. **Claude Desktop** (through the `mcp-remote` bridge), in `claude_desktop_config.json`:
  121. ```json
  122. {
  123. "mcpServers": {
  124. "github-gateway": {
  125. "command": "npx",
  126. "args": [
  127. "mcp-remote",
  128. "https://abc123.execute-api.us-east-1.amazonaws.com/mcp",
  129. "--header",
  130. "Authorization:${AUTH_HEADER}"
  131. ],
  132. "env": { "AUTH_HEADER": "Bearer <your access token>" }
  133. }
  134. }
  135. }
  136. ```
  137. ## Security model
  138. | Threat | Control |
  139. |---|---|
  140. | Unauthenticated access | JWT authorizer on every route (asserted in CDK tests); handlers also fail closed if claims are missing |
  141. | 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) |
  142. | 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) |
  143. | 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 |
  144. | Write access through the gateway | Client issues GET only; tools are read-only; classic tokens with write scopes are rejected at connect time |
  145. | Stale credentials | DynamoDB TTL plus an application-side expiry check (TTL deletion is lazy) |
  146. | Abuse and runaway agents | Stage throttling (20 rps, burst 40); upstream rate limits are per user |
  147. | Data loss | PITR on the table, key and table retained on stack deletion, KMS rotation on |
  148. | Path traversal and injection in tool args | Schema validation with patterns for owner and repo; `.` and `..` path segments rejected; paths URL-encoded |
  149. ## Design decisions
  150. - **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.
  151. - **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.
  152. - **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.
  153. - **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.
  154. - **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.
  155. ## Testing
  156. ```bash
  157. python -m venv .venv && . .venv/bin/activate
  158. pip install -r requirements-dev.txt
  159. pytest # 45 tests: protocol, tools, connect flow, token store
  160. cd cdk && npm ci && npm test # 9 CDK assertion tests: encryption, auth, IAM
  161. ```
  162. 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.
  163. ## Roadmap
  164. - Implement the MCP authorization spec (OAuth 2.0 protected resource metadata) so clients can sign in through the browser instead of pasting a JWT.
  165. - GitHub App user-to-server tokens instead of personal access tokens.
  166. - Pluggable upstreams behind the same connect and tool interfaces.
  167. - WAF and per-user quotas in DynamoDB.
  168. ## License
  169. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.