Skip to content
Back to search

mcp-gateway

An envoy-based MCP Gateway that integrates with Istio and policy attachment mechanisms for authN, authZ, rate limiting and more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Kuadrant/mcp-gateway with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Kuadrant/mcp-gateway'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kuadrant--mcp-gateway/badge.svg)](/listings/kuadrant--mcp-gateway)

HTML

<a href="/listings/kuadrant--mcp-gateway"><img src="/api/listings/kuadrant--mcp-gateway/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Minimal Installation (bring your own infrastructure)

If you already have a Kubernetes cluster with [Gateway API](https://gateway-api.sigs.k8s.io/guides/) installed, install just the MCP Gateway components:

# Install Gateway API CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml
# Install MCP Gateway (quotes required for zsh)
kubectl apply -k 'https://github.com/Kuadrant/mcp-gateway/config/install?ref=main'

This installs: - MCP gateway CRDs - Broker/router deployment - Controller deployment - RBAC resources

See [config/install/README.md](./config/install/README.md) for details and prerequisites.

Development Environment

For a complete local environment with all dependencies (Istio, Gateway API, Keycloak, everything test server):

make local-env-setup

This sets up: - a `kind` cluster - Istio as a Gateway API provider - MCP Gateway components (Broker / Router / Controller) - the everything test server - example MCPServerRegistration

To deploy all test servers, run `make deploy-test-servers` after setup.

Adding e2e tests

If you are adding an e2e test, please consider using the claude slash command provided : [e2e command](./.claude/commands/e2e-tests.md). You can of course still add them manually if you prefer.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 232 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Gateway
  2. An Envoy-based gateway for Model Context Protocol (MCP) servers, enabling aggregation and routing of multiple MCP servers behind a single endpoint.
  3. ## Vision
  4. See [VISION.md](./VISION.md) for project vision and design principles.
  5. ## Architecture
  6. See [docs/design/overview.md](./docs/design/overview.md) for technical architecture.
  7. ## Quick Install
  8. ### Minimal Installation (bring your own infrastructure)
  9. If you already have a Kubernetes cluster with [Gateway API](https://gateway-api.sigs.k8s.io/guides/) installed, install just the MCP Gateway components:
  10. ```bash
  11. # Install Gateway API CRDs
  12. kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml
  13. # Install MCP Gateway (quotes required for zsh)
  14. kubectl apply -k 'https://github.com/Kuadrant/mcp-gateway/config/install?ref=main'
  15. ```
  16. This installs:
  17. - MCP gateway CRDs
  18. - Broker/router deployment
  19. - Controller deployment
  20. - RBAC resources
  21. See [config/install/README.md](./config/install/README.md) for details and prerequisites.
  22. ### Development Environment
  23. For a complete local environment with all dependencies (Istio, Gateway API, Keycloak, everything test server):
  24. ```bash
  25. make local-env-setup
  26. ```
  27. This sets up:
  28. - a `kind` cluster
  29. - Istio as a Gateway API provider
  30. - MCP Gateway components (Broker / Router / Controller)
  31. - the everything test server
  32. - example MCPServerRegistration
  33. To deploy all test servers, run `make deploy-test-servers` after setup.
  34. #### Adding e2e tests
  35. If you are adding an e2e test, please consider using the claude slash command provided : [e2e command](./.claude/commands/e2e-tests.md). You can of course still add them manually if you prefer.
  36. ## Quick start with MCP Inspector
  37. Set up a local kind cluster with the Broker, Router & Controller running.
  38. These components are built during the make target into a single image and loaded into the cluster.
  39. Also sets up an Istio Gateway API Gateway with the everything test server behind the broker/router.
  40. ```bash
  41. make local-env-setup
  42. # Or with custom ports (defaults: 8001->30080->8080 for MCP Broker/Gateway, 8002->30081->8002 for Keycloak)
  43. KIND_HOST_PORT_MCP_GATEWAY=8090 KIND_HOST_PORT_KEYCLOAK=8453 make local-env-setup
  44. ```
  45. > **Note**: If you change these ports, be mindful that some examples or YAML resources may need to be updated manually to use the updated port. You should check for anything that connects to `mcp.127-0-0-1.sslip.io` or `keycloak.127-0-0-1.sslip.io` and update the port numbers accordingly.
  46. >
  47. > **Keycloak Port Requirement**: The host port for Keycloak needs to match the internal listener port (8002 in the default configuration) because there is a `hostAlias` in Authorino in the local dev environment that ensures Authorino calls back to Keycloak at the correct IP/port to validate tokens. If you change the host port (e.g., to 9999), you must also change the listener in the gateway to 9999, otherwise Authorino cannot reach Keycloak over the internal Kubernetes network.
  48. Run the MCP Inspector and connect to the gateway
  49. ```bash
  50. make inspect-gateway
  51. ```
  52. This will start MCP Inspector and automatically open it with the correct URL for the gateway.
  53. ## Example OAuth setup: Keycloak as an ACL Server
  54. After running the Quick start above (`make local-env-setup`), configure OAuth authentication with a single command:
  55. ```bash
  56. make auth-example-setup
  57. ```
  58. This will:
  59. - Install Keycloak
  60. - Set up a Keycloak realm with user/groups/client scopes, including group mappings for tool permissions
  61. - Configure the mcp-broker with OAuth environment variables
  62. - Apply AuthPolicy for token validation/exchange on the /mcp endpoint, including tool authorization via keycloak group mappings (both via Keycloak)
  63. - Apply additional OAuth configurations
  64. - Deploy several test MCP servers including OIDC-enabled MCP server
  65. The mcp-broker now serves OAuth discovery information at `/.well-known/oauth-protected-resource`.
  66. Finally, open MCP Inspector at http://localhost:6274/?transport=streamable-http&serverUrl=http://mcp.127-0-0-1.sslip.io:8001/mcp
  67. When you click connect with MCP Inspector, you should be redirected to Keycloak. There you will need to login as the MCP user with password mcp. You now should only be able to access tools based on the ACL configuration.
  68. You can modify tool authorization permissions by signing in to keycloak at https://keycloak.127-0-0-1.sslip.io:8002/ as the `admin` user with password `admin`, and modifying the 'Role Mappings' in the 'accounting' Group under the 'mcp' realm.
  69. Each MCP Server is represented as a 'Client', with each tool represented as a 'Role'.
  70. ## Running Modes
  71. ### Standalone Mode (File-based)
  72. Uses a YAML configuration file to define MCP servers:
  73. ```bash
  74. make run
  75. # Or directly:
  76. ./bin/mcp-broker-router --mcp-gateway-config ./config/samples/config.yaml
  77. ```
  78. The broker watches the config file for changes and hot-reloads configuration automatically.
  79. ### Controller Mode (Kubernetes)
  80. Discovers MCP servers dynamically from Kubernetes Gateway API `HTTPRoute` resources:
  81. ```bash
  82. make run-controller
  83. # Or directly:
  84. ./bin/mcp-broker-router --controller
  85. ```
  86. In controller mode:
  87. - Watches `MCPServer` custom resources
  88. - Discovers servers via `HTTPRoute` references
  89. - Generates aggregated configuration in `ConfigMap`, for use by the broker/router
  90. - Exposes health endpoints on `:8081` and metrics on `:8082`
  91. ## Configuration
  92. ### Standalone Configuration
  93. Edit `config/samples/config.yaml`:
  94. ```yaml
  95. servers:
  96. - name: weather-service
  97. url: http://weather.example.com:8080
  98. hostname: weather.example.com
  99. enabled: true
  100. prefix: "weather_"
  101. - name: calendar-service
  102. url: http://calendar.example.com:8080
  103. hostname: calendar.example.com
  104. enabled: true
  105. prefix: "cal_"
  106. ```
  107. ### Kubernetes Configuration
  108. #### MCPServerRegistration Resource
  109. The `MCPServer` is a Kubernetes Custom Resource that defines an MCP (Model Context Protocol) server to be aggregated by the gateway. It enables discovery and federation of tools from backend MCP servers through Gateway API `HTTPRoute` references.
  110. Each `MCPServer` resource:
  111. - References a single HTTPRoute that points to a backend MCP service
  112. - Configures a prefix to avoid naming conflicts when federating tools
  113. - Enables the controller to automatically discover and configure the broker with available MCP servers
  114. - Maintains status conditions to indicate whether the server is successfully discovered, valid and ready
  115. Create `MCPServer` resources that reference HTTPRoutes:
  116. ```yaml
  117. apiVersion: mcp.kuadrant.io/v1alpha1
  118. kind: MCPServerRegistration
  119. metadata:
  120. name: weather-tools
  121. spec:
  122. targetRef:
  123. group: gateway.networking.k8s.io
  124. kind: HTTPRoute
  125. name: weather-route
  126. prefix: weather_
  127. ---
  128. apiVersion: mcp.kuadrant.io/v1alpha1
  129. kind: MCPServerRegistration
  130. metadata:
  131. name: calendar-tools
  132. spec:
  133. targetRef:
  134. group: gateway.networking.k8s.io
  135. kind: HTTPRoute
  136. name: calendar-route
  137. prefix: cal_
  138. ```
  139. ## Command Line Flags
  140. ```bash
  141. --mcp-router-address # gRPC ext_proc address (default: 0.0.0.0:50051)
  142. --mcp-broker-public-address # HTTP broker address (default: 0.0.0.0:8080)
  143. --mcp-gateway-config # Config file path (default: ./config/samples/config.yaml)
  144. --controller # Enable Kubernetes controller mode
  145. ```
  146. ### OAuth Configuration
  147. The broker serves OAuth protected resource discovery at `/.well-known/oauth-protected-resource`. In controller-managed deployments, configure this via the `oauthProtectedResource` field on `MCPGatewayExtension`:
  148. ```bash
  149. kubectl patch mcpgatewayextension mcp-gateway-extension -n mcp-system --type='merge' \
  150. -p='{"spec":{"oauthProtectedResource":{"authorizationServers":["https://keycloak.example.com/realms/mcp"],"scopesSupported":["basic","read","write","groups"]}}}'
  151. ```
  152. Only `authorizationServers` is required. Defaults: `resourceName` = `"MCP Server"`, `resource` = `https://<publicHost>/mcp`, `bearerMethodsSupported` = `["header"]`, `scopesSupported` = `["basic"]`.
  153. See the [authentication guide](docs/guides/authentication.md) and [MCPGatewayExtension reference](docs/reference/mcpgatewayextension.md) for full details.
  154. For standalone (non-Kubernetes) usage, the broker reads `OAUTH_RESOURCE_NAME`, `OAUTH_RESOURCE`, `OAUTH_AUTHORIZATION_SERVERS`, `OAUTH_BEARER_METHODS_SUPPORTED`, and `OAUTH_SCOPES_SUPPORTED` environment variables directly.
  155. **Response Format:**
  156. The endpoint returns a JSON response following the OAuth Protected Resource discovery specification:
  157. ```json
  158. {
  159. "resource_name": "MCP Server",
  160. "resource": "https://mcp.example.com/mcp",
  161. "authorization_servers": [
  162. "https://keycloak.example.com/realms/mcp"
  163. ],
  164. "bearer_methods_supported": ["header"],
  165. "scopes_supported": ["basic", "read", "write"]
  166. }
  167. ```
  168. ## Deployment to OpenShift
  169. A script is available to deploy the MCP Gateway and dependent services to an OpenShift cluster. Utilize the steps described [here](./config/openshift/README.md) to facilitate the deployment.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.