{"id":51534005,"url":"https://github.com/swarmclawai/mcp-gateway","last_synced_at":"2026-07-09T06:30:48.125Z","repository":{"id":352102651,"uuid":"1213348897","full_name":"swarmclawai/mcp-gateway","owner":"swarmclawai","description":"Local MCP gateway that fans out to N downstream MCP servers, namespaces tools, and lazy-loads schemas — so your coding agent's context isn't eaten by MCP boilerplate. Built for agents.","archived":false,"fork":false,"pushed_at":"2026-06-29T12:25:21.000Z","size":102,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-29T14:24:00.785Z","etag":null,"topics":["ai-agents","aider","claude-code","cli","cline","coding-agents","context-window","cursor","llm","mcp","mcp-gateway","mcp-proxy","model-context-protocol","typescript","windsurf"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/swarmclawai.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":null,"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":"2026-04-17T09:34:24.000Z","updated_at":"2026-06-29T12:25:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/swarmclawai/mcp-gateway","commit_stats":null,"previous_names":["swarmclawai/mcp-gateway"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/swarmclawai/mcp-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmclawai%2Fmcp-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmclawai%2Fmcp-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmclawai%2Fmcp-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmclawai%2Fmcp-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swarmclawai","download_url":"https://codeload.github.com/swarmclawai/mcp-gateway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarmclawai%2Fmcp-gateway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35290235,"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-07-09T02:00:07.329Z","response_time":57,"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":["ai-agents","aider","claude-code","cli","cline","coding-agents","context-window","cursor","llm","mcp","mcp-gateway","mcp-proxy","model-context-protocol","typescript","windsurf"],"created_at":"2026-07-09T06:30:47.472Z","updated_at":"2026-07-09T06:30:48.120Z","avatar_url":"https://github.com/swarmclawai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-gateway\n\n\u003e **Your coding agent is spending 47,000 tokens on MCP boilerplate before you type a word.** `mcp-gateway` fans out to your downstream MCP servers, namespaces their tools, and only exposes what you ask for. Agents discover the rest on demand via `mcp_tool_search`.\n\n[![npm version](https://img.shields.io/npm/v/@swarmclawai/mcp-gateway.svg)](https://www.npmjs.com/package/@swarmclawai/mcp-gateway)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![CI](https://github.com/swarmclawai/mcp-gateway/actions/workflows/ci.yml/badge.svg)](https://github.com/swarmclawai/mcp-gateway/actions/workflows/ci.yml)\n\n\u003cp align=\"center\"\u003e\n  \u003c!-- TODO: replace with recorded before/after GIF of /context in Claude Code --\u003e\n  \u003cimg src=\"./docs/assets/before-after.gif\" alt=\"Claude Code /context dropping from 47K to 3K tokens after installing mcp-gateway\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n## 30-second install\n\n```bash\n# Drop-in for Claude Code\nnpx @swarmclawai/mcp-gateway@latest add claude-code\n\n# Or Cursor, Cline, Windsurf\nnpx @swarmclawai/mcp-gateway@latest add cursor\nnpx @swarmclawai/mcp-gateway@latest add cline\nnpx @swarmclawai/mcp-gateway@latest add windsurf\n```\n\nThat edits the agent's MCP config (with a `.bak` backup) so it talks to one gateway endpoint instead of N individual servers. Then:\n\n```bash\n# Generate a starter config and edit to taste\nnpx @swarmclawai/mcp-gateway@latest init --write\n\n# See how many tokens each downstream server is spending on tool schemas\nnpx @swarmclawai/mcp-gateway@latest token-report\n```\n\n## How it works\n\n```\n┌─────────────────┐        ┌─────────────────┐        ┌─────────────────┐\n│ Claude Code,    │        │                 │  stdio │ filesystem      │\n│ Cursor, Cline,  │ stdio  │  mcp-gateway    ├────────┤ github          │\n│ Windsurf, ...   ├────────┤  (one endpoint) │        │ sentry          │\n│                 │        │                 │  http  │ your HTTP MCP   │\n└─────────────────┘        └─────────────────┘        └─────────────────┘\n                                    │\n                                    └── only `alwaysExpose` tools are bound\n                                        at startup. Rest surface via\n                                        `mcp_tool_search` on demand.\n```\n\n- **Namespaces downstream tools.** Two servers can both expose `read_file` — you see `fs__read_file` and `github__read_file`.\n- **Lazy-loads by default.** Tools from `alwaysExpose: false` servers stay hidden until an agent calls `mcp_tool_search({query: \"...\"})`, which promotes them for the rest of the session.\n- **Speaks stdio upstream.** Or streamable-HTTP — see [HTTP mode](#http-mode).\n- **Stdio or HTTP downstream.** Set `command` for local processes, `url` for remote MCP servers.\n\n## Config\n\n`mcp-gateway.config.json` at your project root (or `--config \u003cpath\u003e`):\n\n```json\n{\n  \"version\": 1,\n  \"namespaceSeparator\": \"__\",\n  \"servers\": [\n    {\n      \"name\": \"fs\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \".\"],\n      \"alwaysExpose\": true\n    },\n    {\n      \"name\": \"github\",\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"-e\", \"GITHUB_PERSONAL_ACCESS_TOKEN\", \"ghcr.io/github/github-mcp-server\"],\n      \"alwaysExpose\": false\n    },\n    {\n      \"name\": \"sentry\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@sentry/mcp-server@latest\"],\n      \"alwaysExpose\": [\"issue_details\"]\n    },\n    {\n      \"name\": \"remote\",\n      \"url\": \"https://mcp.example.com/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer ${SECRET_TOKEN}\" },\n      \"alwaysExpose\": false\n    }\n  ]\n}\n```\n\n- `alwaysExpose: true` — every tool from this server is in your agent's context on startup.\n- `alwaysExpose: false` — tools aren't exposed at first; `mcp_tool_search` surfaces them on demand.\n- `alwaysExpose: [\"tool_a\", \"tool_b\"]` — only the listed tools are pre-exposed.\n- Each server is **stdio** (`command`) or **HTTP** (`url`), not both.\n\n## The `mcp_tool_search` meta-tool\n\nThe gateway always exposes one built-in tool: `mcp_tool_search({query, limit?})`. Agents call it to discover lazy tools by name or description keywords. Matched tools are promoted for the rest of the session and start showing up in subsequent `list_tools` responses.\n\nThis is the feature that makes `alwaysExpose: false` actually usable — an agent doesn't need to know a tool exists up-front, it searches when it needs one.\n\n## HTTP mode\n\n```bash\n# Listen on http://127.0.0.1:3477/mcp instead of stdio\nnpx @swarmclawai/mcp-gateway@latest start --http --port 3477\n```\n\nUseful when:\n- Your agent runs on a server (e.g. SwarmClaw on a VPS) and wants to talk to a local gateway over the network.\n- You want to run one persistent gateway and point multiple agents at it.\n- Your client prefers streamable-HTTP to spawning stdio child processes.\n\n## Commands\n\n| Command | Purpose |\n|---|---|\n| `add \u003cagent\u003e` | Install the gateway into an agent's MCP config (claude-code, cursor, cline, windsurf) |\n| `init` | Create a starter `mcp-gateway.config.json` |\n| `validate` | Validate the config without connecting |\n| `status` | Connect to each downstream and report status + tool counts |\n| `token-report` | Estimate token cost per downstream |\n| `add-server` | Append a downstream server to the config |\n| `start` | Start the gateway (stdio by default, `--http --port` for streamable-HTTP) |\n| `help-agents` | Print the machine-readable command catalog |\n\nEvery command accepts `--json` and returns a one-line JSON envelope. Exit codes: `0` success, `1` user error, `2` internal error.\n\n## Token leaderboard\n\nEvery week, `mcp-gateway` benchmarks a curated set of popular MCP servers and publishes the results: which are the leanest, which are the heaviest, how much you're spending.\n\nSee [`bench/leaderboard.md`](./bench/leaderboard.md) — or open a PR against [`bench/servers.json`](./bench/servers.json) to add your server.\n\n## Used by\n\n- **[SwarmClaw](https://github.com/swarmclawai/swarmclaw)** — self-hosted autonomous-agent runtime. Embeds `@swarmclawai/mcp-core` (the library half of this repo) so every SwarmClaw agent gets lazy tool exposure + `mcp_tool_search` without running a separate gateway process.\n\nShip something on top of it? Open a PR and we'll add you.\n\n## Library use (`@swarmclawai/mcp-core`)\n\nThe pure primitives — config parsing, downstream multiplexing, token estimation, `McpRequestRouter`, `McpMultiClient`, `mcp_tool_search` — live in a separate package so embedders can use them in-process:\n\n```bash\npnpm add @swarmclawai/mcp-core\n```\n\n```ts\nimport { McpMultiClient } from \"@swarmclawai/mcp-core\";\n\nconst mc = new McpMultiClient({\n  config: {\n    version: 1,\n    servers: [\n      { name: \"fs\", command: \"npx\", args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \".\"], alwaysExpose: true },\n      { name: \"github\", command: \"docker\", args: [...], alwaysExpose: false },\n    ],\n  },\n});\nawait mc.connectEager();\nconst tools = await mc.listExposedTools();\n// → [fs__read_file, fs__write_file, ..., mcp_tool_search]\n```\n\nSee the [package README](./packages/mcp-core/README.md) for the full API surface.\n\n## Built for coding agents\n\nEvery `@swarmclawai/*` CLI follows the same agent conventions so Claude Code, Cursor, Cline, Codex, Factory Droid, Cursor Agent et al can drive them without guessing:\n\n- `--json` everywhere, one-line envelope on stdout\n- Stderr for logs, stdout for data\n- Stable exit codes: `0` / `1` / `2`\n- Non-interactive by default\n- `mcp-gateway help-agents` returns the entire command catalog as JSON\n\nSee [`AGENTS.md`](./AGENTS.md) for the full machine-readable reference.\n\n## Roadmap\n\n- Tool **profiles / groups**: `\"profile\": \"coding\"` exposes a curated subset across servers\n- Schema compression for lazy-exposed tools\n- Per-agent session state so gateways serving multiple clients don't cross-promote tools\n- Per-tool deny/allow list beyond the namespace prefix\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md).\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswarmclawai%2Fmcp-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswarmclawai%2Fmcp-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswarmclawai%2Fmcp-gateway/lists"}