{"id":50779305,"url":"https://github.com/rad-security/agentkeeper-mcp-gateway","last_synced_at":"2026-06-12T02:01:13.790Z","repository":{"id":354534998,"uuid":"1224067821","full_name":"rad-security/agentkeeper-mcp-gateway","owner":"rad-security","description":"AgentKeeper MCP Gateway with runtime enforcement and Claude Desktop/Cowork posture collection","archived":false,"fork":false,"pushed_at":"2026-06-05T20:11:36.000Z","size":153,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T22:06:13.262Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rad-security.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-28T23:43:25.000Z","updated_at":"2026-06-05T20:11:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rad-security/agentkeeper-mcp-gateway","commit_stats":null,"previous_names":["rad-security/agentkeeper-mcp-gateway"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rad-security/agentkeeper-mcp-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rad-security%2Fagentkeeper-mcp-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rad-security%2Fagentkeeper-mcp-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rad-security%2Fagentkeeper-mcp-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rad-security%2Fagentkeeper-mcp-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rad-security","download_url":"https://codeload.github.com/rad-security/agentkeeper-mcp-gateway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rad-security%2Fagentkeeper-mcp-gateway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34225351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-06-12T02:00:36.385Z","updated_at":"2026-06-12T02:01:13.778Z","avatar_url":"https://github.com/rad-security.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgentKeeper MCP Gateway\n\nOpen-source MCP gateway with threat detection, warn mode, and fail-open design.\n\nSits between any MCP client (Cursor, Claude Code, Windsurf, Copilot) and your MCP servers. Inspects every tool call for threats, sensitive data, and policy violations. Deploys in 60 seconds.\n\n## Quick Start\n\n```bash\n# Install from the latest GitHub Release\ncurl -fsSL https://www.agentkeeper.dev/install-gateway.sh | bash\n\n# Preview supported local MCP client migration\nagentkeeper-mcp-gateway configure-ide --dry-run\n\n# Move supported MCP client configs behind Gateway\nagentkeeper-mcp-gateway configure-ide\n\n# Check discovery, routing, auth, and next steps\nagentkeeper-mcp-gateway list --health\n```\n\nRestart the MCP client after `configure-ide`, then make one real tool call. The gateway proxies routed MCP traffic, detects threats in real time, and logs everything locally. Manual `agentkeeper-mcp-gateway add` is still available for unsupported config sources, gateway-native admin setup, and lab cases, but it is not the default rollout workflow.\n\n## Local Development\n\nThis repository is the standalone Go MCP gateway used by AgentKeeper. The main\nAgentKeeper app, Helm chart, and dashboard live in\n[`rad-security/agentkeeper-web`](https://github.com/rad-security/agentkeeper-web).\n\nRequirements:\n\n- Go 1.23.3 or compatible\n- Node.js/npm if you want to test common `npx` MCP servers locally\n\nBuild and test:\n\n```bash\ngit clone https://github.com/rad-security/agentkeeper-mcp-gateway.git\ncd agentkeeper-mcp-gateway\ngo test ./...\ngo run . version\ngo build -o bin/agentkeeper-mcp-gateway .\n```\n\nRun a local gateway with a disposable filesystem MCP server:\n\n```bash\ngo run . add filesystem \"npx -y @modelcontextprotocol/server-filesystem /tmp\"\ngo run . list\ngo run . server\n```\n\nImportant directories:\n\n```text\ncmd/                       Cobra CLI commands\ninternal/config/           Config path resolution and env overrides\ninternal/detection/        Threat and sensitive-data detection\ninternal/ideconfig/        Claude/Cursor IDE config rewrites\ninternal/policy/           Audit/enforce policy behavior\ninternal/proxy/            MCP proxy path\ninternal/skillinventory/   Local skill inventory scan and check-in\ninternal/telemetry/        Dashboard event upload\n```\n\nConfig resolution is documented below in \"Headless / Config-Managed Install\".\nDo not hardcode production AgentKeeper API keys while testing; use local config\nfiles or disposable dashboard keys.\n\n## What It Detects\n\n**36 threat detection patterns** running locally at sub-50ms:\n\n| Category | Examples |\n|---|---|\n| Credential exfiltration | API keys piped to curl, SSH keys sent to external endpoints |\n| Reverse shells | bash, netcat, python, perl, ruby, base64-encoded |\n| Prompt injection | Override instructions, persona hijacking, jailbreak attempts |\n| Security control bypass | Firewall disable, SELinux/AppArmor teardown, AV kill |\n| Supply chain attacks | Suspicious package installs from raw URLs |\n| Tool poisoning | Hidden instructions in MCP tool descriptions |\n| Sensitive data | Stripe/AWS/GitHub keys, credit cards, SSNs, private keys, JWTs |\n\n## Two Modes\n\n**Audit (default):** Full proxy, full visibility, zero blocking. See every tool call, every threat, every server. Zero developer friction.\n\n```bash\nagentkeeper-mcp-gateway server\n```\n\n**Enforce:** Same proxy. Policies enforced — threats blocked or warned per configuration.\n\n```bash\nagentkeeper-mcp-gateway server --enforce\n```\n\n## Warn Mode\n\nWhen a threat is detected in warn mode, the warning is returned to the AI client as context. The AI sees the threat and can self-correct — no developer interruption, no retry loops.\n\nThis is unique to AgentKeeper. Other gateways either block silently or pass through without feedback.\n\n## Fail-Open Design\n\nThe gateway never breaks your tools:\n\n- Detection error: tool call proceeds, event logged\n- API timeout: falls back to local detection\n- Gateway crash: watchdog spawns pass-through proxy instantly\n- Network down: uses cached policy, queues events\n\n## Connect to Dashboard\n\nOptional. Get fleet-wide visibility, team policies, and identity-aware access controls.\n\n```bash\nagentkeeper-mcp-gateway auth login\n```\n\nOpens your browser for device authorization. Once connected, events stream to the dashboard and team policies sync every 60 seconds.\n\n## CLI Reference\n\n```bash\n# Server management\nagentkeeper-mcp-gateway add \u003cname\u003e \u003ccommand\u003e    # fallback/admin only\nagentkeeper-mcp-gateway remove \u003cname\u003e\nagentkeeper-mcp-gateway list [--health] [--json]\n\n# Gateway\nagentkeeper-mcp-gateway server [--enforce]\nagentkeeper-mcp-gateway logs [-f] [-l 50]\nagentkeeper-mcp-gateway scan\nagentkeeper-mcp-gateway export --format json|csv --since 2026-04-01\n\n# Configuration\nagentkeeper-mcp-gateway config show\nagentkeeper-mcp-gateway auth login|status|logout\nagentkeeper-mcp-gateway completion zsh|bash|fish\n\n# IDE integration (zero-touch)\nagentkeeper-mcp-gateway configure-ide [--dry-run] [--ide=claude-code|claude-desktop|cursor|cowork]\n```\n\n## Zero-touch IDE wiring\n\n`configure-ide` rewrites every supported local MCP client config to route through the gateway. One command, all supported clients, fully idempotent. This includes Claude Desktop, Claude Code settings, Claude Code user-scoped and project-scoped `~/.claude.json` servers, Cursor, and current Cowork local/plugin/remote MCP sources.\n\n```bash\nagentkeeper-mcp-gateway configure-ide --dry-run   # preview; writes nothing\nagentkeeper-mcp-gateway configure-ide              # apply\n```\n\nFor Cowork sources created after setup, run `agentkeeper-mcp-gateway cowork guard` from a login item/service, or rerun `configure-ide`. Native Cowork cloud connectors that are not represented as local MCP sources require the AgentKeeper Cowork ZIP/guardrail path; the standalone gateway can only govern MCP traffic it can route.\n\nSupports **Claude Code** (`~/.claude/settings.json`), **Claude Desktop** (macOS + Linux), and **Cursor** (`~/.cursor/mcp.json`). For each detected IDE it:\n\n1. Backs up the existing config to `*.agentkeeper-backup-\u003cunix-nanos\u003e`\n2. Migrates any already-registered MCP servers into the gateway's own config (environment variables and all)\n3. Rewrites the IDE's `mcpServers` map to a single entry pointing at the gateway\n4. Preserves every non-MCP top-level key verbatim (`permissions`, `preferences`, etc.)\n\nA second invocation is a no-op — the command detects a correctly-wired config and skips the write entirely. Safe to run from a login hook, a postinstall script, or on every Kandji reapply.\n\n## Manual fallback/admin registration\n\nUse `add` only when no supported local MCP client config can be migrated, or when an admin intentionally wants a gateway-native server entry.\n\n```bash\nagentkeeper-mcp-gateway add github \"npx -y @modelcontextprotocol/server-github\"\nagentkeeper-mcp-gateway add remote https://api.example.com/mcp --header \"Authorization:Bearer tok\"\n```\n\nFor enterprise rollout, prefer `configure-ide --dry-run`, `configure-ide`, MCP client restart, a real tool call, and `list --health`.\n\n## Cowork MCP Gateway Routing\n\nCowork can expose MCP servers from Claude Desktop config, plugin `.mcp.json`\nfiles, and remote MCP session state. The gateway must be the only MCP path; a\nbackend that is both imported into AgentKeeper and still present as a native\nCowork remote MCP source can bypass AgentKeeper telemetry.\n\nImportant boundary: the standalone local gateway governs Cowork traffic when\nCowork invokes the local `agentkeeper-mcp-gateway server` MCP process. This\nrelease covers MCP backends that are discoverable on disk as Claude Desktop\nconfig, Cowork plugin `.mcp.json`, or Cowork remote MCP session config. It\nimports those backends, ensures Cowork has a gateway MCP entrypoint to attach\nto, and removes direct remote MCP session entries that would bypass the\ngateway.\n\nConnector calls that Cowork never represents in local MCP config can still\nexecute through Claude's cloud-managed connector API without invoking the local\ngateway process. Those cloud-only connector calls require the AgentKeeper\nCowork plugin ZIP path:\n\n```text\nhttps://www.agentkeeper.dev/downloads/cowork/latest/agentkeeper-cowork-guardrail.zip\n```\n\nRun the Cowork-specific configure command after install and after plugin or\nremote MCP changes:\n\n```bash\nagentkeeper-mcp-gateway cowork configure --dry-run\nagentkeeper-mcp-gateway cowork configure\nagentkeeper-mcp-gateway cowork doctor --strict\n```\n\n`cowork configure` imports discovered local/plugin/remote MCP backends into the\ngateway config, ensures Claude Desktop/Cowork has an\n`agentkeeper-mcp-gateway server` MCP entrypoint, rewrites local `.mcp.json`\nfiles to point at that entrypoint, and disables direct Cowork\n`remoteMcpServersConfig` entries after backing up each touched file to\n`*.agentkeeper-backup-\u003cunix-nanos\u003e`.\n\nThe local MCP success condition is:\n\n```text\nverdict: cowork_local_mcp_routed_native_connectors_require_zip\ndirect_count: 0\ngateway_backend_count: \u003e0\n```\n\n`cowork doctor` includes a redacted `gateway_backends` inventory so an\nentrypoint-only deployment cannot look healthy. Any direct Cowork MCP source is\na bypass risk. `cowork doctor --strict` exits non-zero until direct sources are\nremoved, and also exits non-zero when Cowork is wired to the gateway entrypoint\nbut the gateway config has no backend MCP servers.\n\nIf your deployment requires governance of Cowork native/cloud connectors, run:\n\n```bash\nagentkeeper-mcp-gateway cowork doctor --strict --require-native-connectors\n```\n\nThat command intentionally exits non-zero because standalone local MCP routing\ncannot cover connector calls that are not exposed to the local gateway process;\ninstall the AgentKeeper Cowork plugin ZIP and verify with `cowork-status.sh`\nafter a real Cowork tool action.\n\n## Headless / Config-Managed Install\n\nThe gateway is designed to work under a fleet config-management tool (Kandji, Ansible, Jamf, MDM) that does not know any individual developer's home directory. Drop a config at `/etc/agentkeeper-mcp-gateway/config.json`, or set env vars, and the gateway picks it up.\n\n**Config path resolution (in priority order):**\n\n| # | Source | Example |\n|---|---|---|\n| 1 | `--config` flag | `agentkeeper-mcp-gateway --config /opt/ck/cfg.json server` |\n| 2 | `$AGENTKEEPER_CONFIG` env var | `export AGENTKEEPER_CONFIG=/opt/ck/cfg.json` |\n| 3 | `$XDG_CONFIG_HOME/agentkeeper-mcp-gateway/config.json` (if file exists) | per-user override |\n| 4 | `~/.config/agentkeeper-mcp-gateway/config.json` (if file exists) | dev default |\n| 5 | `/etc/agentkeeper-mcp-gateway/config.json` (if file exists) | system-wide, fleet-deploy target |\n| fallback | `~/.config/agentkeeper-mcp-gateway/config.json` | created on first write |\n\n**Environment overrides:**\n\n| Field | Env var | Rule |\n|---|---|---|\n| `api_key` | `AGENTKEEPER_API_KEY` | File wins when set; env fills blanks only. |\n| `api_url` | `AGENTKEEPER_API_URL` | File wins when set to a non-default value; env fills blanks and the factory default. |\n\nThe file-wins-over-env rule is deliberate — rotate the API key by re-rendering the config file, not by setting a shell env var that silently shadows the real config.\n\n**Checking the resolved state:**\n\n```bash\n$ agentkeeper-mcp-gateway config show\n# config path: /etc/agentkeeper-mcp-gateway/config.json\n# api_key:     file\n# api_url:     default\n{ \"mode\": \"audit\", ... }\n```\n\n`config show` prints the resolved path and labels every overridable field as `file`, `env`, or `default`.\n\n**Sample systemd unit (Linux):**\n\n```ini\n# /etc/systemd/system/agentkeeper-mcp-gateway.service\n[Unit]\nDescription=AgentKeeper MCP Gateway\nAfter=network-online.target\n\n[Service]\nUser=agentkeeper\nExecStart=/usr/local/bin/agentkeeper-mcp-gateway server\nEnvironment=AGENTKEEPER_CONFIG=/etc/agentkeeper-mcp-gateway/config.json\nRestart=on-failure\n\n[Install]\nWantedBy=multi-user.target\n```\n\n## Architecture\n\n```\nMCP Client (Cursor, Claude Code, Windsurf)\n    |\n    v\nagentkeeper-mcp-gateway (local binary, 8MB)\n    |\n    +---\u003e Detection Engine (36 patterns, \u003c50ms)\n    +---\u003e Policy Engine (dashboard + local config)\n    +---\u003e Event Logger (JSONL + batch upload)\n    +---\u003e Watchdog (fail-open recovery)\n    |\n    v\nMCP Servers (GitHub, filesystem, Slack, etc.)\n```\n\n## Works With the Claude Code Plugin\n\nFor complete coverage, deploy both:\n\n- **MCP Gateway** — covers MCP tool calls across all IDEs\n- **Claude Code Plugin** — covers native tools (Bash, Read, Write, Edit) that MCP can't see\n\nBoth report to the same dashboard. Single pane of glass.\n\n## Compliance\n\n| Framework | Controls |\n|---|---|\n| OWASP Agentic Top 10 | ASI01-ASI05 |\n| OWASP LLM Top 10 | LLM01, LLM02, LLM03, LLM06 |\n| SOC 2 | CC6.1, CC6.6, CC7.2, CC9.2 |\n| EU AI Act | Art. 9, 12, 14, 15 |\n\n## License\n\nMIT\n\n## Links\n\n- [Dashboard](https://www.agentkeeper.dev)\n- [Docs](https://www.agentkeeper.dev/docs)\n- [Claude Code Plugin](https://github.com/rad-security/agentkeeper-web/tree/main/plugin)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frad-security%2Fagentkeeper-mcp-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frad-security%2Fagentkeeper-mcp-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frad-security%2Fagentkeeper-mcp-gateway/lists"}