{"id":41675943,"url":"https://github.com/eznix86/mcp-gateway","last_synced_at":"2026-01-24T18:12:19.970Z","repository":{"id":333346224,"uuid":"1136977950","full_name":"eznix86/mcp-gateway","owner":"eznix86","description":"Too much tools in context. Use a gateway","archived":false,"fork":false,"pushed_at":"2026-01-18T22:39:34.000Z","size":291,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-19T01:36:42.330Z","etag":null,"topics":["gateway","llm","mcp-server","opencode"],"latest_commit_sha":null,"homepage":"","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/eznix86.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-01-18T17:42:59.000Z","updated_at":"2026-01-18T22:39:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/eznix86/mcp-gateway","commit_stats":null,"previous_names":["eznix86/mcp-gateway"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/eznix86/mcp-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eznix86%2Fmcp-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eznix86%2Fmcp-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eznix86%2Fmcp-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eznix86%2Fmcp-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eznix86","download_url":"https://codeload.github.com/eznix86/mcp-gateway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eznix86%2Fmcp-gateway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28733634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T17:51:25.893Z","status":"ssl_error","status_checked_at":"2026-01-24T17:50:48.377Z","response_time":89,"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":["gateway","llm","mcp-server","opencode"],"created_at":"2026-01-24T18:12:19.891Z","updated_at":"2026-01-24T18:12:19.953Z","avatar_url":"https://github.com/eznix86.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Gateway\n\n[![npm version](https://img.shields.io/npm/v/@eznix/mcp-gateway)](https://www.npmjs.com/package/@eznix/mcp-gateway)\n[![npm downloads](https://img.shields.io/npm/dm/@eznix/mcp-gateway)](https://www.npmjs.com/package/@eznix/mcp-gateway)\n[![License](https://img.shields.io/npm/l/@eznix/mcp-gateway)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/eznix86/mcp-gateway)](https://github.com/eznix86/mcp-gateway/stargazers)\n\nMCP Gateway is a server aggregation tool that connects multiple Model Context Protocol (MCP) servers into a single gateway, exposing all tools from connected servers through unified search, describe, and invoke interfaces and it exposes only 5 tools.\n\n## The Context Limit Problem\n\nWhen connecting an client (Claude Code, Opencode, etc.) to multiple MCP servers, each server lists all its tools. With 10+ MCPs each exposing 10-50 tools, you can easily exceed 500+ tool descriptions in the system prompt:\n\n```\n10 servers × 20 tools each = 200+ tool descriptions\nEach tool: 200-500 chars → 40KB-100KB of description just for tool schemas!\n```\n\nThis creates two problems:\n1. **Context overflow**: Many LLMs hit their context limit before any conversation happens\n2. **Cognitive overload**: LLMs struggle to choose the right tool from hundreds of options\n\n## The Gateway Solution\n\nMCP Gateway solves this by providing **tool search** instead of dumping all tool schemas:\n\n```\n┌─────────────┐    gateway.search    ┌─────────────────┐    kubernetes::pods_list    ┌──────────────────┐\n│  AI Client  │ ───────────────────► │   MCP Gateway   │ ─────────────────────────►  │  Kubernetes MCP  │\n│             │                      │                 │                             │                  │\n│             │ ◄────────────────────│                 │ ◄─────────────────────────  │                  │\n└─────────────┘   pods_list schema   └─────────────────┘         pods output         └──────────────────┘\n```\n\n## How It Works\n\nMCP Gateway operates as both an MCP client (connecting to upstream servers) and an MCP server (exposing tools to downstream clients):\n\n```\n┌──────────────┐      MCP       ┌─────────────────┐      MCP       ┌──────────────────┐\n│  AI Client   │ ◄────────────  │   MCP Gateway   │ ◄────────────  │  Upstream Server │\n│ (Claude, etc)│                │  (this gateway) │                │  (playwright,    │\n└──────────────┘                └─────────────────┘                │   kubernetes...) │\n                                                                   └──────────────────┘\n```\n\n1. Gateway starts and reads configuration\n2. For each configured upstream server, Gateway connects via stdio (local) or HTTP/WebSocket (remote)\n3. Gateway fetches the tool catalog from each server\n4. All tools are indexed in a unified catalog with search capabilities\n5. AI clients connect to Gateway and use `gateway.search` to find relevant tools\n6. Only the tools the client actually needs are invoked\n\nYou will notice around ~40% reduction of initial token used.\n\n## Installation\n\n### Claude Code\n\nAdd to your Claude MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"gateway\": {\n      \"command\": \"bunx\",\n      \"args\": [\"@eznix/mcp-gateway@latest\"]\n    }\n  }\n}\n```\n\n### OpenCode\n\nAdd to your OpenCode MCP configuration:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"mcp-gateway\": {\n      \"type\": \"local\",\n      \"command\": [\"bunx\", \"@eznix/mcp-gateway@latest\"]\n    },\n  }\n}\n```\n\nYou may append your global AGENTS.md (`~/.config/opencode/AGENTS.md`) with this [template](./templates/AGENTS.md).\n\nYou may now just simple enumerate the MCP available.\n\n## Configuration\n\nMCP Gateway reads configuration from a JSON file. By default, it looks for:\n\n1. Path provided as first command-line argument\n2. `MCP_GATEWAY_CONFIG` environment variable\n3. `~/.config/mcp-gateway/config.json`\n\n### Configuration Format\n\n```json\n{\n  \"local-server\": {\n    \"type\": \"local\",\n    \"command\": [\"bun\", \"run\", \"/path/to/server.ts\"],\n  },\n  \"remote-server\": {\n    \"type\": \"remote\",\n    \"url\": \"https://mcp.example.com\",\n    \"enabled\": true\n  },\n  \"websocket-server\": {\n    \"type\": \"remote\",\n    \"url\": \"wss://mcp.example.com/ws\",\n    \"enabled\": true\n  }\n}\n```\n\nEach entry specifies:\n- `type`: `\"local\"` or `\"remote\"`\n- `command` (local only): Array with command and arguments to spawn the upstream server\n- `url` (remote only): Full URL of the remote MCP server\n- `transport` (optional, remote only): Override transport detection (`\"streamable_http\"` or `\"websocket\"`). Usually auto-detected from URL protocol.\n- `enabled`: Set to false to skip connecting to this server\n\n### Docker\n\nRun MCP Gateway in Docker with HTTP transport:\n\n```bash\n# Build the image\ndocker build -t mcp-gateway .\n\n# Run with config mounted\ndocker run -p 3000:3000 \\\n  -v ./examples/config.json:/home/gateway/.config/mcp-gateway/config.json:ro \\\n  mcp-gateway\n```\n\n**Endpoints:**\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /` | Gateway info and endpoints |\n| `GET /health` | Health check |\n| `/mcp` | MCP protocol endpoint |\n\n**Example:**\n\n```bash\ncurl http://localhost:3000/\n# {\"name\":\"MCP Gateway\",...,\"endpoints\":{\"mcp\":\"/mcp\",\"health\":\"/health\"}}\n\ncurl http://localhost:3000/health\n# {\"status\":\"ok\"}\n```\n\n### Remote Server Configuration\n\nRemote servers are auto-detected based on the URL protocol:\n- `http://` or `https://` → Streamable HTTP (recommended)\n- `ws://` or `wss://` → WebSocket\n\n```json\n{\n  \"gh-grep\": {\n    \"type\": \"remote\",\n    \"url\": \"https://mcp.grep.app\"\n  },\n  \"custom-websocket\": {\n    \"type\": \"remote\",\n    \"url\": \"wss://my-server.com/mcp\"\n  }\n}\n```\n\n## Available Tools\n\n### `gateway.search`\n\nSearch for tools across all connected servers.\n\n```typescript\n{\n  query: \"kubernetes pods\",\n  limit: 10,  // optional, max 50\n  filters: {\n    server: \"kubernetes\",  // optional, filter by server name\n  }\n}\n```\n\nReturns matching tools with relevance scores. Tools matching in name are boosted.\n\n### `gateway.describe`\n\nGet detailed information about a specific tool.\n\n```typescript\n{\n  id: \"kubernetes::pods_list\"  // format: serverKey::toolName\n}\n```\n\nReturns the full tool schema including inputSchema.\n\n### `gateway.invoke`\n\nExecute a tool synchronously and get immediate results.\n\n```typescript\n{\n  id: \"kubernetes::pods_list\",\n  args: { namespace: \"default\" },\n  timeoutMs: 30000  // optional, default 30 seconds\n}\n```\n\n### `gateway.invoke_async`\n\nStart an asynchronous tool execution. Returns a job ID for polling.\n\n```typescript\n{\n  id: \"some-server::long-running-tool\",\n  args: { ... },\n  priority: 10,  // optional, higher values run first\n  timeoutMs: 60000\n}\n```\n\n### `gateway.invoke_status`\n\nCheck the status of an async job.\n\n```typescript\n{\n  jobId: \"job_123456789_abc123\"\n}\n```\n\n## Tool ID Format\n\nAll gateway tools use the format `serverKey::toolName` to identify tools:\n\n```\nkubernetes::pods_list\nplaywright::browser_navigate\ngithub::create_issue\n```\n\nThe `serverKey` is the key name in your configuration file.\n\n## Architecture\n\n### Components\n\n- **MCPGateway class**: Main orchestrator\n- **Upstream connection manager**: Manages connections to MCP servers (stdio for local, HTTP/WebSocket for remote)\n- **Tool catalog**: In-memory index of all available tools with metadata\n- **Job queue**: Handles async tool invocations with priority ordering and concurrency limits (max 3 concurrent by default)\n- **Search engine**: MiniSearch with BM25 scoring and fuzzy matching\n\n### Search Algorithm\n\nThe search uses [MiniSearch](https://github.com/lucaong/minisearch) with BM25 ranking:\n\n- **BM25 scoring**: Relevance algorithm\n- **Field boosting**: Name matches (3x), title matches (2x), description/server matches (1x)\n- **Fuzzy matching**: Handles typos with 0.2 threshold (e.g., \"kubenetes\" → finds \"kubernetes\")\n- **Prefix search**: Partial word matching (e.g., \"pod\" matches \"pods_list\")\n\n### Contributing\n\n```bash\ngit clone https://github.com/eznix86/mcp-gateway.git\ncd mcp-gateway\nbun install\n\n# Run locally (stdio transport)\nbun run index.ts\n\n# Run with Docker (HTTP transport on port 3000)\nbun run docker:build \u0026\u0026 bun run docker:run\n```\n\n## License\n\nMIT License. See the [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feznix86%2Fmcp-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feznix86%2Fmcp-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feznix86%2Fmcp-gateway/lists"}