{"id":43449128,"url":"https://github.com/github/gh-aw-mcpg","last_synced_at":"2026-06-05T21:00:57.929Z","repository":{"id":328049705,"uuid":"1114078059","full_name":"github/gh-aw-mcpg","owner":"github","description":"Github Agentic Workflows MCP Gateway","archived":false,"fork":false,"pushed_at":"2026-04-03T00:33:31.000Z","size":21149,"stargazers_count":108,"open_issues_count":27,"forks_count":19,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-03T00:39:50.248Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/github.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-10T21:43:52.000Z","updated_at":"2026-04-01T23:24:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/github/gh-aw-mcpg","commit_stats":null,"previous_names":["githubnext/gh-aw-mcpg","github/gh-aw-mcpg"],"tags_count":154,"template":false,"template_full_name":null,"purl":"pkg:github/github/gh-aw-mcpg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fgh-aw-mcpg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fgh-aw-mcpg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fgh-aw-mcpg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fgh-aw-mcpg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github","download_url":"https://codeload.github.com/github/gh-aw-mcpg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fgh-aw-mcpg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31426193,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T02:22:46.605Z","status":"ssl_error","status_checked_at":"2026-04-05T02:22:33.263Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-03T01:25:47.992Z","updated_at":"2026-04-05T06:01:26.084Z","avatar_url":"https://github.com/github.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Gateway\n\nA gateway for Model Context Protocol (MCP) servers.\n\nThis gateway is used with [GitHub Agentic Workflows](https://github.com/github/gh-aw) via the `sandbox.mcp` configuration to provide MCP server access to AI agents running in sandboxed environments.\n\n## Quick Start\n\n1. **Pull the Docker image** (when available):\n   ```bash\n   docker pull ghcr.io/github/gh-aw-mcpg:latest\n   ```\n\n2. **Create a configuration file** (`config.json`):\n   ```json\n   {\n     \"gateway\": {\n       \"apiKey\": \"${MCP_GATEWAY_API_KEY}\"\n     },\n     \"mcpServers\": {\n       \"github\": {\n         \"type\": \"stdio\",\n         \"container\": \"ghcr.io/github/github-mcp-server:latest\",\n         \"env\": {\n           \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"\"\n         }\n       }\n     }\n   }\n   ```\n\n3. **Run the container**:\n   ```bash\n   docker run --rm -i \\\n     -e MCP_GATEWAY_PORT=8000 \\\n     -e MCP_GATEWAY_DOMAIN=localhost \\\n     -e MCP_GATEWAY_API_KEY=your-secret-key \\\n     -v /var/run/docker.sock:/var/run/docker.sock \\\n     -v /path/to/logs:/tmp/gh-aw/mcp-logs \\\n     -p 8000:8000 \\\n     ghcr.io/github/gh-aw-mcpg:latest \u003c config.json\n   ```\n\nThe gateway starts in routed mode on `http://0.0.0.0:8000`, proxying MCP requests to your configured backend servers.\n\n**Required flags:**\n- `-i`: Enables stdin for passing JSON configuration\n- `-v /var/run/docker.sock`: Required for spawning backend MCP servers\n- `-p 8000:8000`: Port mapping must match `MCP_GATEWAY_PORT`\n\n## Guard Policies\n\nGuard policies enforce integrity filtering and private-data leaking at the gateway level, restricting what data agents can access and where they can write. Each server can have either an `allow-only` or a `write-sink` policy.\n\n### allow-only (source servers)\n\nRestricts which repositories a guard allows and at what integrity level:\n\n```json\n\"github\": {\n  \"type\": \"stdio\",\n  \"container\": \"ghcr.io/github/github-mcp-server:latest\",\n  \"env\": { \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"\" },\n  \"guard-policies\": {\n    \"allow-only\": {\n      \"repos\": [\"github/gh-aw-mcpg\", \"github/gh-aw\"],\n      \"min-integrity\": \"unapproved\"\n    }\n  }\n}\n```\n\n**`repos`** — Repository access scope:\n- `\"all\"` — All repositories accessible by the token\n- `\"public\"` — Public repositories only\n- `[\"owner/repo\"]` — Exact match\n- `[\"owner/*\"]` — All repos under owner\n- `[\"owner/prefix*\"]` — Repos matching prefix\n\n**`min-integrity`** — Minimum integrity level required for content items. Levels from highest to lowest:\n- `\"merged\"` — Objects reachable from main branch\n- `\"approved\"` — Members (OWNER, MEMBER, COLLABORATOR); private repo items; trusted bots\n- `\"unapproved\"` — Contributors (CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR)\n- `\"none\"` — All objects (FIRST_TIMER, NONE)\n- `blocked` — Items from `blocked-users` (always denied; not a configurable value)\n\n**`blocked-users`** *(optional)* — Array of GitHub usernames whose content is unconditionally blocked. Items from these users receive `blocked` integrity (below `none`) and are always denied, even when `min-integrity` is `\"none\"`. Cannot be overridden by `approval-labels`.\n\n**`approval-labels`** *(optional)* — Array of GitHub label names that promote a content item's effective integrity to `approved` when present. Enables human-review gates where a maintainer labels an item to allow it through. Uses `max(base, approved)` so it never lowers integrity. Does not override `blocked-users`.\n\n**`trusted-users`** *(optional)* — Array of GitHub usernames whose content is unconditionally elevated to `approved` integrity. Useful for granting specific external contributors (e.g., trusted open-source maintainers) the same treatment as repository members, without lowering `min-integrity` globally. Uses `max(base, approved)` so it never lowers integrity. Does not override `blocked-users`.\n\n```json\n\"guard-policies\": {\n  \"allow-only\": {\n    \"repos\": [\"myorg/*\"],\n    \"min-integrity\": \"approved\",\n    \"blocked-users\": [\"spam-bot\", \"compromised-user\"],\n    \"approval-labels\": [\"human-reviewed\", \"safe-for-agent\"],\n    \"trusted-users\": [\"alice\", \"trusted-contributor\"]\n  }\n}\n```\n\nFor comprehensive documentation on integrity filtering, see the [Integrity Filtering Reference](https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/integrity.md).\n\n### write-sink (output servers)\n\n**Required for ALL output servers** when guards are enabled. Marks a server as a write-only channel that accepts writes from agents with matching secrecy labels:\n\n```json\n\"safeoutputs\": {\n  \"type\": \"stdio\",\n  \"container\": \"ghcr.io/github/safe-outputs:latest\",\n  \"guard-policies\": {\n    \"write-sink\": {\n      \"accept\": [\"private:github/gh-aw-mcpg\", \"private:github/gh-aw\"]\n    }\n  }\n}\n```\n\nThe `accept` entries must match the secrecy tags assigned by the guard. Key mappings:\n\n| `allow-only.repos` | `write-sink.accept` |\n|---|---|\n| `\"all\"` or `\"public\"` | `[\"*\"]` |\n| `[\"owner/repo\"]` | `[\"private:owner/repo\"]` |\n| `[\"owner/*\"]` | `[\"private:owner\"]` |\n| `[\"owner/prefix*\"]` | `[\"private:owner/prefix*\"]` |\n\nSee **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)** for the complete mapping table and accept pattern reference.\n\n## Architecture\n\n```\n                    ┌─────────────────────────────────────┐\n                    │           MCP Gateway               │\n  Client ──────────▶  /mcp/{serverID}  (routed mode)      │\n  (JSON-RPC 2.0)    │ /mcp             (unified mode)     │\n                    │                                     │\n                    │  ┌─────────────┐  ┌──────────────┐  │\n                    │  │ Guards      │  │ Auth (7.1)   │  │\n                    │  │ (WASM)      │  │ API Key      │  │\n                    │  └──────┬──────┘  └──────────────┘  │\n                    │         │                           │\n                    │  ┌──────▼──────┐  ┌──────────────┐  │\n                    │  │ GitHub MCP  │  │ Safe Outputs │  │\n                    │  │ (stdio/     │  │ (write-sink) │  │\n                    │  │  Docker)    │  │              │  │\n                    │  └─────────────┘  └──────────────┘  │\n                    └─────────────────────────────────────┘\n```\n\n**Transport**: JSON-RPC 2.0 over stdio (containerized Docker) or HTTP (session state preserved)\n\n**Routing**: Routed mode (`/mcp/{serverID}`) exposes each backend at its own endpoint. Unified mode (`/mcp`) routes to all configured servers through a single endpoint.\n\n**Security**: WASM-based DIFC guards enforce secrecy and integrity labels per request. Guards are loaded from `MCP_GATEWAY_WASM_GUARDS_DIR` and assigned per-server. Authentication uses plain API keys per MCP spec 7.1 (`Authorization: \u003capi-key\u003e`).\n\n**Logging**: Per-server log files (`{serverID}.log`), unified `mcp-gateway.log`, markdown workflow previews (`gateway.md`), and machine-readable `rpc-messages.jsonl`.\n\n## API Endpoints\n\n- `POST /mcp/{serverID}` — Routed mode (default): JSON-RPC request to specific server\n- `POST /mcp` — Unified mode: JSON-RPC request routed to configured servers\n- `GET /health` — Health check; returns JSON `{\"status\":\"healthy\" | \"unhealthy\",\"specVersion\":\"...\",\"gatewayVersion\":\"...\",\"servers\":{...}}`\n\nSupported MCP methods: `tools/list`, `tools/call`, and any other method (forwarded as-is).\n\n## Proxy Mode\n\nThe gateway can also run as an HTTP forward proxy (`awmg proxy`) that intercepts GitHub API requests from tools like `gh` CLI and applies the same DIFC filtering:\n\n```bash\nawmg proxy \\\n  --guard-wasm guards/github-guard/github_guard.wasm \\\n  --policy '{\"allow-only\":{\"repos\":[\"org/repo\"],\"min-integrity\":\"approved\"}}' \\\n  --github-token \"$GITHUB_TOKEN\" \\\n  --listen localhost:8080\n```\n\nThis maps ~25 REST URL patterns and GraphQL queries to guard tool names, then runs the same 6-phase DIFC pipeline used by the MCP gateway. See [docs/PROXY_MODE.md](docs/PROXY_MODE.md) for full documentation.\n\n## Further Reading\n\n| Topic | Link |\n|-------|------|\n| **Proxy Mode** | [docs/PROXY_MODE.md](docs/PROXY_MODE.md) — HTTP forward proxy for DIFC filtering of `gh` CLI and REST/GraphQL requests |\n| **Integrity Filtering** | [Integrity Filtering Reference](https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/integrity.md) — Integrity levels, blocked-users, approval-labels, and filtering configuration |\n| **Configuration Reference** | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) — Server fields, TOML/JSON formats, guard-policy details, custom schemas, gateway fields, validation rules |\n| **Environment Variables** | [docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md) — All env vars for production, development, Docker, and guard configuration |\n| **Full Specification** | [MCP Gateway Configuration Reference](https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/mcp-gateway.md) — Upstream spec with complete validation rules |\n| **Guard Response Labeling** | [docs/GUARD_RESPONSE_LABELING.md](docs/GUARD_RESPONSE_LABELING.md) — How guards label MCP responses with secrecy/integrity tags |\n| **HTTP Backend Sessions** | [docs/HTTP_BACKEND_SESSION_ID.md](docs/HTTP_BACKEND_SESSION_ID.md) — Session ID management for HTTP transport backends |\n| **Architecture Patterns** | [docs/MCP_SERVER_ARCHITECTURE_PATTERNS.md](docs/MCP_SERVER_ARCHITECTURE_PATTERNS.md) — MCP server design patterns and compatibility |\n| **Gateway Compatibility** | [docs/GATEWAY_COMPATIBILITY_QUICK_REFERENCE.md](docs/GATEWAY_COMPATIBILITY_QUICK_REFERENCE.md) — Quick reference for gateway compatibility |\n| **Security Model** | [docs/aw-security.md](docs/aw-security.md) — Security architecture overview |\n| **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) — Development setup, building, testing, project structure |\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fgh-aw-mcpg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub%2Fgh-aw-mcpg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fgh-aw-mcpg/lists"}