github-gateway
Provides read-only tools against the GitHub REST API using each user's own fine-grained personal access token: list the repositories a user can access (most recently updated first), read a text file up to 200 KB or list a directory, search issues and pull requests with GitHub search qualifiers (e.g. repo:octo/app is:open label:bug), and list pull requests in a repository by state. Tokens are validated at connect time (write-scoped classic tokens rejected) and envelope-encrypted per user with KMS; the client can only issue GET requests.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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)" --> GHRequest 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 |
| Repositories the user can access, most recently updated first |
| Read a text file (up to 200 KB) or list a directory |
| GitHub issue and PR search, e.g. |
| 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=90Outputs 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" # revokeClassic 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 |
Over-broad Lambda permissions | MCP Lambda: |
Tokens leaking into logs | Tokens and request bodies are never logged; user IDs are logged as a truncated SHA-256; |
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; |
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, andGET /mcpreturns405as 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
isErrorresults the model can read and recover from.Lazy credential access.
initialize,ping, andtools/listnever touch DynamoDB or KMS. The token is decrypted only fortools/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, IAMThe 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Unofficial GitHub MCP — wraps the GitHub public REST API (no auth required for public endpoints)
GitHub Private MCP Pack — access private repos, org data via OAuth. Complements the existing…
Access the GitHub API, enabling file operations, repository management, search functionality, and…
Create, deploy, and operate MCP servers directly from your GitHub repositories.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables read-only access to the canonical-vault GitHub repository through MCP, letting clients list files, retrieve file contents and history, inspect commits, and search code.5MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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
- FlicenseNot gradedqualityDmaintenanceEnables read-only browsing and querying of GitHub repositories, including listing repos, reading files, fetching READMEs, searching code, and viewing commit history via MCP.-
- AlicenseNot gradedqualityCmaintenanceGives any MCP client read-only tools for private GitHub repositories, with OAuth-based authentication and an allowlist of GitHub logins.MIT