MCPGateway Guide

Overview

MCPGateway is a Kubemoot CRD that deploys an MCP gateway - the central hub that routes agent tool calls to MCPServers. Agents connect to the gateway (not individual MCPServers), and the gateway discovers and manages connections to all matching MCPServers.

Architecture

Agent Runtime
    │
    │  KUBEMOOT_GATEWAY_ENDPOINT
    ▼
MCPGateway (Deployment + Service)
    │
    ├── MCPServer: kubernetes-mcp  (via label selector)
    ├── MCPServer: nats-mcp        (via label selector)
    ├── MCPServer: github-mcp      (via label selector)
    └── MCPServer: fetch-mcp       (via label selector)

The gateway:

1. Discovers MCPServers matching its mcpServerSelector
2. Connects to each server’s HTTP/SSE endpoint (provided by the mcp-bridge for stdio servers)
3. Performs MCP protocol initialization (initialize → notifications/initialized → tools/list)
4. Aggregates all discovered tools and exposes them to agents
5. Routes tool calls from agents to the correct MCPServer

Implementations

The reference deployment uses the kubemoot implementation. The gateway image comes from KubemootConfig (spec.images.mcpGateway).

Spec Reference

MCPGatewayAuth

MetaToolsConfig

CredentialPolicy

Credential policies define how dynamically discovered MCP servers get authentication. First matching policy wins. Explicit MCPServer CRs always take priority.

Status

Server Selection

The gateway discovers MCPServers via mcpServerSelector. The most common pattern uses Helm release labels:

spec:
  mcpServerSelector:
    matchLabels:
      app.kubernetes.io/instance: homelab-pilot

This selects all MCPServers deployed by the same Helm release. MCPServers must also have registry.enabled: true (the default).

If mcpServerSelector is empty, all MCPServers in the namespace are registered.

MCP Protocol Initialization

The gateway must complete the MCP protocol handshake before tools are available:

1. Gateway sends initialize request to the MCPServer (via bridge SSE endpoint)
2. Server responds with capabilities
3. Gateway sends notifications/initialized notification
4. Gateway sends tools/list to discover available tools

For stdio/bridge transport, the gateway uses fire-and-forget initialization: send initialize, wait 500ms, send notifications/initialized, wait 500ms, then discover tools. A retry (2s delay) runs if 0 tools are found initially.

Tool List Changes

A server’s tools can change while its URL stays the same: its pod is replaced with new arguments (for example --toolsets=core,config,helm adds helm_list), its container restarts with a new image, or the server changes its tools at runtime. The gateway lists the tools again when one of these states shows:

A re-list that returns no tools, or fails, keeps the tools already known (a replacement server may still be starting) and marks the server ERROR, so the next re-registration connects again. When several re-lists overlap, only the most recently started one updates the list. GET /admin/tools and GET /admin/servers/{id}/tools always serve the latest list.

Agents read GET /admin/tools when they start and again before an evaluation once their copy is older than 60 seconds (10 seconds while it is empty). A tool that is added, removed, or given a new description or input schema reaches running agents that way, without restarting them.

Example

Example Gateway

apiVersion: kubemoot.ai/v1alpha1
kind: MCPGateway
metadata:
  name: example-gateway
spec:
  implementation: kubemoot
  port: 8080
  replicas: 1
  mcpServerSelector:
    matchLabels:
      app.kubernetes.io/instance: homelab-pilot
  adminUI: true
  auth:
    enabled: false
    type: none

Gateway with Tool Index and Meta-Tools

apiVersion: kubemoot.ai/v1alpha1
kind: MCPGateway
metadata:
  name: gateway-with-search
spec:
  implementation: kubemoot
  mcpServerSelector:
    matchLabels:
      app.kubernetes.io/instance: homelab-pilot
  toolIndex:
    vectorStore:
      type: pgvector
      host: pgvector.pgvector
      port: 5432
      database: vectors
      secretRef: pgvector-credentials
    embeddingModel:
      provider: ollama
      endpoint: http://ollama.ollama-a:11434
      model: nomic-embed-text
  metaTools:
    enabled: true
    maxResultsPerSearch: 10

Gateway with Credential Policies

apiVersion: kubemoot.ai/v1alpha1
kind: MCPGateway
metadata:
  name: gateway-with-creds
spec:
  implementation: kubemoot
  credentialPolicies:
    - categories: ["kubernetes", "k8s"]
      serviceAccountName: mcp-k8s-access
    - categories: ["github"]
      secretRef: github-token
    - categories: ["*"]
      transport: stdio

Related CRDs: MCPCatalog, MCPQualityPolicy, MCPServerReport

The MCPGateway works with three related CRDs for dynamic server discovery and quality filtering. These are used by the autonomic onboarding system (see onboarding-guide.md).

MCPCatalog

MCPCatalog defines an external MCP server registry to discover servers from. The gateway references catalogs via catalogRefs.

Short name: mcpcat

Status tracks serversDiscovered, serversAllowed, serversBlocked, and per-server details including quality decisions.

apiVersion: kubemoot.ai/v1alpha1
kind: MCPCatalog
metadata:
  name: official-registry
spec:
  type: official-registry
  url: https://registry.modelcontextprotocol.io/v0/servers
  syncInterval: "24h"
  maxServers: 50
  qualityPolicyRef: quality-policy

Warning: Auto-syncing the official MCP registry can deploy community servers that crash. Keep MCPCatalog disabled until quality filtering is robust enough to prevent broken deployments.

MCPQualityPolicy

MCPQualityPolicy defines trust and quality filtering for discovered MCP servers. Evaluation order: allowing → blocking → tested → considering (AI evaluation).

Short name: mqp

Evaluation Pipeline

Discovered Server
    │
    ├── Allowing list match? ──── YES → Allow immediately
    │                              (essential infrastructure MCPs)
    ├── Blocking list match? ──── YES → Block immediately
    │                              (known bad, deprecated, suspicious)
    ├── Tested (MCPServerReport)? ── successRate > threshold → Allow
    │                              ── verdict: "avoid" → Block
    │
    └── Considering (AI eval) ──── agentRef evaluates via LLM
                                   ── confidence > threshold → decision
                                   ── below threshold → fallbackAction

ConsideringConfig

apiVersion: kubemoot.ai/v1alpha1
kind: MCPQualityPolicy
metadata:
  name: quality-policy
spec:
  allowing:
    - author: "modelcontextprotocol"  # Official MCP servers
    - name: "mcp/kubernetes"          # Essential infrastructure
  blocking:
    - name:
        type: glob
        value: "*crypto*"
      reason: "Cryptocurrency-related servers not needed"
    - author:
        type: exact
        value: "known-bad-actor"
      reason: "Known malicious publisher"
  tested:
    enabled: true
    minSuccessRate: "0.8"
    blockBroken: true
  considering:
    enabled: true
    agentRef: quality-evaluator
    confidenceThreshold: "0.7"
    fallbackAction: deny

MCPServerReport

MCPServerReport tracks deployment and runtime experience for an MCP server. One report per server accumulates trial records, enabling Kubemoot to learn which servers work reliably and which to avoid.

Short name: mcprpt

Verdicts

Trial Phases

Each trial records where in the lifecycle it succeeded or failed:

Spec (identity + admin curation)

Status (continuously updated)

apiVersion: kubemoot.ai/v1alpha1
kind: MCPServerReport
metadata:
  name: kafka-mcp-report
spec:
  serverName: kafka-mcp
  githubUrl: https://github.com/example/kafka-mcp
  registryType: docker
status:
  verdict: use
  recommendedTransport: stdio
  successRate: "0.95"
  successCount: 19
  failureCount: 1

Admin override example:

kubectl patch mcprpt kafka-mcp-report --type=merge -p \
  '{"spec":{"adminVerdict":"avoid","adminNotes":"Crashes under load","adminAuthor":"ops-team"}}'

Troubleshooting

0 tools discovered

Check the full chain:

1. MCPServer pods are Running and Ready
2. MCPServer status.endpoint is set
3. MCPGateway’s mcpServerSelector matches the server’s labels
4. Gateway pod logs for initialization errors

Gateway caches failed connections

If the gateway fails to connect to an MCPServer on first registration, it caches the failure and never retries. Delete the gateway pod to force re-connection:

kubectl delete pod -l kubemoot.ai/mcpgateway=<name>

Agent has no tools

Verify the agent’s KUBEMOOT_GATEWAY_ENDPOINT env var points to the correct gateway service:

kubectl exec deploy/<agent-name> -- env | grep GATEWAY

MCP bridge session ID missing

The bridge SSE endpoint event must include sessionId= in the data field. If the gateway logs show “skipping initialization” for a server, check the bridge version - older versions may not include the session ID.