{
  "markdown": "# Vengtoo MCP Gateway\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/Node-≥18-339933.svg)](https://nodejs.org)\n[![npm](https://img.shields.io/npm/v/@vengtoo/mcp-gateway)](https://www.npmjs.com/package/@vengtoo/mcp-gateway)\n\n**Authorization gateway for AI agents and MCP tool calls.**\n\n> Open-source. Drop-in. Works with any MCP client.\n\n## Why\n\nAI agents connected to MCP servers can call any tool they have access to: read your database, delete files, execute arbitrary SQL. Vengtoo MCP Gateway puts a policy enforcement point between the agent and those tools, so every call is authorized before it executes.\n\n## What it does\n\n- Sits between MCP clients (Claude Code, Cursor, VS Code, GitHub Copilot) and any MCP server\n- Intercepts every tool call and checks authorization before forwarding\n- Two modes: **cloud** (Vengtoo Cloud API) and **local** (Vengtoo Agent + .rego policy file)\n- Full audit trail of every tool invocation: subject, tool name, arguments, and decision are logged as structured JSON:\n\n```json\n{\"ts\":\"2026-05-25T10:03:11.482Z\",\"level\":\"info\",\"msg\":\"mcp_tool_call\",\"subject\":\"agent:ai-assistant\",\"tool\":\"database__query\",\"allowed\":true,\"latency_ms\":0.8}\n```\n\n## Quick Start\n\n1. Install and start the [Vengtoo Agent](https://github.com/vengtoo/agent). The agent runs locally and evaluates your authorization policy; no cloud account needed.\n\n```bash\ngo install github.com/vengtoo/agent/cmd/agent@latest\nvengtoo-agent --policy ./policy.rego\n```\n\nCreate a `policy.rego` to define what your agent can do:\n\n```rego\npackage vengtoo.mcp\n\ndefault allow := false\n\n# Allow read-only tools\nallow if { input.resource.name == \"database__query\" }\nallow if { input.resource.name == \"database__list_tables\" }\n\n# Allow writes, but block destructive SQL\nallow if {\n    input.resource.name == \"database__execute\"\n    not contains(lower(input.resource.attributes.sql), \"drop\")\n    not contains(lower(input.resource.attributes.sql), \"delete from\")\n}\n```\n\nSee [`demo/policies/`](demo/policies/) for more examples including Kubernetes namespace protection.\n\n2. Create a `gateway.config.json`:\n\n```json\n{\n  \"vengtoo\": {\n    \"agentUrl\": \"http://127.0.0.1:8181\"\n  },\n  \"subject\": \"agent:ai-assistant\",\n  \"servers\": {\n    \"database\": {\n      \"command\": \"node\",\n      \"args\": [\"./my-database-mcp-server.js\"]\n    }\n  }\n}\n```\n\n3. Add to your MCP client (e.g. Claude Code):\n\n```bash\nclaude mcp add --transport stdio vengtoo-gateway -- \\\n  npx vengtoo-mcp-gateway --config /path/to/gateway.config.json\n```\n\n## Configuration\n\n### Config schema\n\n| Field              | Type   | Required | Description                                                    |\n| ------------------ | ------ | -------- | -------------------------------------------------------------- |\n| `vengtoo.agentUrl`  | string | \\*       | URL of local Vengtoo Agent (local mode)                         |\n| `vengtoo.cloudUrl`  | string | \\*       | URL of Vengtoo Cloud API (cloud mode)                           |\n| `vengtoo.apiKey`    | string |          | API key from [Vengtoo Cloud](https://console.vengtoo.com) (or set `VENGTOO_API_KEY` env var) |\n| `vengtoo.timeoutMs` | number |          | Authorization request timeout (default: 5000)                  |\n| `subject`          | string | yes      | Identity of the agent making tool calls                        |\n| `subjectType`      | string |          | Subject type (default: `\"agent\"`)                              |\n| `resourceType`     | string |          | Resource type for authorization checks (default: `\"mcp_tool\"`) |\n| `servers`          | object | yes      | Map of downstream MCP servers to proxy                         |\n| `transport`        | string |          | Caller transport: `\"stdio\"` (default) or `\"http\"`, see [Transport](#transport) |\n| `http`             | object |          | HTTP transport settings (used when `transport` is `\"http\"`)    |\n\n\\* Provide either `agentUrl` (local mode) or `cloudUrl` (cloud mode).\n\nEach entry in `servers` has:\n\n| Field     | Type     | Required | Description                      |\n| --------- | -------- | -------- | -------------------------------- |\n| `command` | string   | yes      | Command to spawn the MCP server  |\n| `args`    | string[] |          | Command arguments                |\n| `env`     | object   |          | Additional environment variables |\n\n## Modes\n\n### Cloud mode\n\nConnect to Vengtoo Cloud for managed policies:\n\n```json\n{\n  \"vengtoo\": {\n    \"cloudUrl\": \"https://api.vengtoo.com/access/v1/evaluation\",\n    \"apiKey\": \"vgt_...\"\n  },\n  \"subject\": \"agent:prod-assistant\",\n  \"servers\": {\n    \"database\": {\n      \"command\": \"node\",\n      \"args\": [\"./db-server.js\"]\n    }\n  }\n}\n```\n\n### Local mode\n\nRun the Vengtoo Agent locally with a .rego policy file for offline, self-contained authorization:\n\n```bash\n# Start the agent with your policy\nvengtoo-agent --policy ./policy.rego\n```\n\n```json\n{\n  \"vengtoo\": {\n    \"agentUrl\": \"http://127.0.0.1:8181\"\n  },\n  \"subject\": \"agent:dev-assistant\",\n  \"servers\": {\n    \"database\": {\n      \"command\": \"node\",\n      \"args\": [\"./db-server.js\"]\n    }\n  }\n}\n```\n\n## Transport\n\nThe gateway exposes its (policy-enforced) tools to callers over one of two transports.\n\n### stdio (default)\n\nRuns as a local subprocess speaking MCP over stdin/stdout: the right choice for a\nsingle desktop agent (Claude Desktop, Cursor, Claude Code). No network surface.\n\n### HTTP (remote)\n\nRuns a [Streamable HTTP](https://modelcontextprotocol.io/) MCP server at a URL, so a\nremote agent (or many concurrent agents) can share one governed gateway. Enable it\nwith `--http` (or `\"transport\": \"http\"` in the config):\n\n```bash\nvengtoo-mcp-gateway --config gateway.config.json --http --port 8808\n```\n\n```json\n{\n  \"vengtoo\": { \"cloudUrl\": \"https://api.vengtoo.com/access/v1/evaluation\", \"apiKey\": \"vgt_...\" },\n  \"subject\": \"agent:prod-assistant\",\n  \"transport\": \"http\",\n  \"http\": {\n    \"port\": 8808,\n    \"host\": \"0.0.0.0\",\n    \"path\": \"/mcp\",\n    \"authTokens\": [\"<caller-token>\"],\n    \"allowedHosts\": [\"gateway.example.com\"]\n  },\n  \"servers\": { \"database\": { \"command\": \"node\", \"args\": [\"./db-server.js\"] } }\n}\n```\n\nHTTP config (`http.*`):\n\n| Field           | Type     | Default       | Description                                                                 |\n| --------------- | -------- | ------------- | --------------------------------------------------------------------------- |\n| `port`          | number   | `8808`        | TCP port to listen on                                                       |\n| `host`          | string   | `127.0.0.1`   | Interface to bind; `0.0.0.0` accepts remote connections                     |\n| `path`          | string   | `/mcp`        | URL path of the MCP endpoint                                                |\n| `callers`       | object[] | -             | Per-caller identity: `{ \"token\": \"...\", \"subject\": \"agent:claude\" }`; each bearer token authorizes as its own subject |\n| `authTokens`    | string[] | -             | Anonymous bearer tokens; grant access, run as the global `subject`         |\n| `allowedHosts`  | string[] | -             | Enables DNS-rebinding protection; rejects requests with an unlisted `Host`  |\n| `allowedOrigins`| string[] | -             | Enables DNS-rebinding protection; rejects requests with an unlisted `Origin`|\n\n**Per-caller identity.** Give each agent its own token and subject, and your policies\n(and audit trail) see each caller's real identity through one shared gateway:\n\n```json\n\"http\": {\n  \"port\": 8808,\n  \"callers\": [\n    { \"token\": \"<claude-token>\", \"subject\": \"agent:claude\" },\n    { \"token\": \"<cursor-token>\", \"subject\": \"agent:cursor\" }\n  ]\n}\n```\n\nAlso settable via `VENGTOO_GATEWAY_HTTP_CALLERS=\"<token>=agent:claude,<token>=agent:cursor\"`.\nSessions are bound to the token that opened them: a different caller presenting another\ncaller's session id gets a 401, so identities cannot cross sessions. Tokens listed in\n`authTokens` (or callers omitted entirely) run as the config's global `subject`.\n\n**Safety:** the gateway **refuses to bind a non-loopback interface with no caller auth**\n(`callers` or `authTokens`). Either configure tokens, or set\n`VENGTOO_GATEWAY_ALLOW_UNAUTHENTICATED=true` to knowingly expose an open endpoint. An\nunauthenticated `GET /healthz` liveness probe is always served.\n\n> ⚠️ **Security: Vengtoo trusts whichever subject this gateway asserts.** The\n> `callers` token→subject mapping above (owned by this gateway's own config) is the\n> correct pattern; it is NOT the same as trusting a client-supplied header. Never\n> change this to derive the subject from a header/field a calling client sends; that\n> would let any caller claim to be any subject and inherit its permissions within\n> your tenant. If you front this gateway with another reverse proxy, make sure that\n> proxy cannot be made to forward an arbitrary caller-chosen bearer token or subject.\n\n## CLI Flags\n\n| Flag                       | Description                                                                            |\n| -------------------------- | -------------------------------------------------------------------------------------- |\n| `--config <path>`          | Path to gateway config file (default: `./gateway.config.json`)                         |\n| `--http`                   | Serve over HTTP instead of stdio                                                       |\n| `--port <n>`               | HTTP listen port (default: `8808`; implies `--http`-compatible config)                |\n| `--host <h>`               | HTTP bind interface (default: `127.0.0.1`)                                             |\n| `--path <p>`               | HTTP endpoint path (default: `/mcp`)                                                   |\n| `--list-tools`             | List all tools from configured downstream servers and exit                             |\n| `--generate-policy [path]` | Generate a starter .rego policy file for the configured tools (default: `policy.rego`) |\n\nEnvironment overrides: `VENGTOO_API_KEY`, `VENGTOO_AGENT_URL`, `VENGTOO_SUBJECT`,\n`VENGTOO_GATEWAY_TRANSPORT` (`http`), `VENGTOO_GATEWAY_PORT` / `PORT`, `VENGTOO_GATEWAY_HOST`,\n`VENGTOO_GATEWAY_PATH`, `VENGTOO_GATEWAY_HTTP_TOKENS` (comma-separated), `VENGTOO_GATEWAY_ALLOW_UNAUTHENTICATED`.\n\n## MCP Client Setup\n\nThe gateway runs as a stdio MCP server. Point your MCP client at it instead of the downstream server directly.\n\n### Claude Code\n\n```bash\nclaude mcp add --transport stdio vengtoo-gateway -- \\\n  npx vengtoo-mcp-gateway --config /path/to/gateway.config.json\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"vengtoo-gateway\": {\n      \"command\": \"npx\",\n      \"args\": [\"vengtoo-mcp-gateway\", \"--config\", \"/path/to/gateway.config.json\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"vengtoo-gateway\": {\n      \"command\": \"npx\",\n      \"args\": [\"vengtoo-mcp-gateway\", \"--config\", \"/path/to/gateway.config.json\"]\n    }\n  }\n}\n```\n\n### VS Code / GitHub Copilot\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"vengtoo-gateway\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"vengtoo-mcp-gateway\", \"--config\", \"/path/to/gateway.config.json\"]\n    }\n  }\n}\n```\n\nSee [`demo/`](demo/) for full end-to-end examples with sample policies.\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md) for what's planned: per-caller OAuth, downstream\nresilience, dynamic tool lists, metrics, remote downstream servers, and more.\n\n## Feedback\n\n- [GitHub Issues](https://github.com/vengtoo/mcp-gateway/issues): Bug reports and feature requests\n- [Documentation](https://docs.vengtoo.com): Guides and API reference\n\n## License\n\nApache-2.0, see [LICENSE](LICENSE).\n",
  "bytes": 11841,
  "sha": "ada8c1936936a70b09d482b5efa7648b137b9ad67ab8e88432314716764dd061",
  "repo_slug": "authzx/mcp-gateway",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_authzx_mcp_gateway_797692da/readme"
}