MCP Server Envoy — Admin API cluster health, config dump, forced drain, and /ready monitoring

Admin API setup and security

Envoy's admin API is configured in the bootstrap YAML under admin.address. It has no built-in authentication — access control must be enforced at the network layer (localhost-only binding or firewall rules). Exposing the admin API publicly allows anyone to drain your proxy, read all xDS state, and send arbitrary runtime modifications.

# envoy.yaml — bootstrap configuration
admin:
  address:
    socket_address:
      address: 127.0.0.1   # Bind to localhost ONLY — never 0.0.0.0 in production
      port_value: 9901

# For Kubernetes sidecars, access via port-forward:
# kubectl port-forward pod/my-pod 9901:9901
# or use the Downward API to get the pod IP and call from within the cluster

// TypeScript client for Envoy admin API
const ENVOY_ADMIN_URL = process.env.ENVOY_ADMIN_URL ?? 'http://localhost:9901';

async function envoyRequest(path: string, options: RequestInit = {}): Promise<string> {
  const res = await fetch(`${ENVOY_ADMIN_URL}${path}`, options);

  if (!res.ok) {
    throw new Error(`Envoy admin ${options.method ?? 'GET'} ${path} → ${res.status}`);
  }

  return res.text();
}

async function envoyJsonRequest(path: string): Promise<any> {
  const text = await envoyRequest(path);
  try {
    return JSON.parse(text);
  } catch {
    throw new Error(`Envoy admin ${path} returned non-JSON: ${text.slice(0, 200)}`);
  }
}

export { envoyRequest, envoyJsonRequest };

Core Envoy MCP tool patterns

import { z } from 'zod';
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
import { envoyRequest, envoyJsonRequest } from './envoy-client.js';

// ---- get_ready_status ----
server.tool(
  'get_ready_status',
  {},
  async () => {
    try {
      const text = await envoyRequest('/ready');
      return { content: [{ type: 'text', text: JSON.stringify({ ready: true, message: text.trim() }) }] };
    } catch {
      return { content: [{ type: 'text', text: JSON.stringify({ ready: false }) }] };
    }
  }
);

// ---- list_clusters ----
// Returns per-endpoint health flags and connection stats
server.tool(
  'list_clusters',
  {
    show_unhealthy_only: z.boolean().default(false),
    cluster_name_filter: z.string().optional()
  },
  async ({ show_unhealthy_only, cluster_name_filter }) => {
    const data = await envoyJsonRequest('/clusters?format=json');

    // cluster_statuses is the array of clusters in JSON format
    let clusters = (data.cluster_statuses ?? []) as any[];

    if (cluster_name_filter) {
      clusters = clusters.filter(c =>
        c.name?.toLowerCase().includes(cluster_name_filter.toLowerCase())
      );
    }

    const result = clusters.map((cluster: any) => {
      const hostStatuses = cluster.host_statuses ?? [];

      const hosts = hostStatuses.map((h: any) => ({
        address: h.address?.socket_address
          ? `${h.address.socket_address.address}:${h.address.socket_address.port_value}`
          : 'unknown',
        health_flags: h.health_status?.failed_active_health_check
          ? '/failed_active_hc'
          : h.health_status?.failed_outlier_check
          ? '/failed_outlier_check'
          : '/healthy',
        healthy: !h.health_status?.failed_active_health_check && !h.health_status?.failed_outlier_check,
        weight: h.weight,
        // Stats: successful, total, error counts
        rq_success: h.stats?.find((s: any) => s.name === 'rq_success')?.value ?? 0,
        rq_total: h.stats?.find((s: any) => s.name === 'rq_total')?.value ?? 0,
        rq_timeout: h.stats?.find((s: any) => s.name === 'rq_timeout')?.value ?? 0,
        cx_active: h.stats?.find((s: any) => s.name === 'cx_active')?.value ?? 0
      }));

      return {
        name: cluster.name,
        is_passthrough: cluster.circuit_breakers === undefined,
        total_hosts: hosts.length,
        healthy_hosts: hosts.filter(h => h.healthy).length,
        unhealthy_hosts: hosts.filter(h => !h.healthy).length,
        hosts: show_unhealthy_only ? hosts.filter(h => !h.healthy) : hosts
      };
    });

    const filtered = show_unhealthy_only
      ? result.filter(c => c.unhealthy_hosts > 0)
      : result;

    return { content: [{ type: 'text', text: JSON.stringify(filtered, null, 2) }] };
  }
);

// ---- get_config_dump ----
// Full xDS state — expensive, call on demand only
server.tool(
  'get_config_dump',
  {
    section: z.enum(['clusters', 'listeners', 'routes', 'endpoints', 'secrets', 'all']).default('clusters')
  },
  async ({ section }) => {
    const path = section === 'all'
      ? '/config_dump'
      : `/config_dump?resource=${section}`;

    const data = await envoyJsonRequest(path);

    // Config dump returns { configs: [ { @type: ..., ... }, ... ] }
    const configs = data.configs ?? [];

    const summary = configs.map((c: any) => ({
      type: c['@type']?.split('/').pop() ?? 'unknown',
      count: c.dynamic_active_clusters?.length
        ?? c.dynamic_listeners?.length
        ?? c.dynamic_route_configs?.length
        ?? c.dynamic_endpoint_configs?.length
        ?? '(see full dump)'
    }));

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ section, config_sections: summary, full_dump: section === 'all' ? data : undefined }, null, 2)
      }]
    };
  }
);

// ---- get_stats ----
// Returns specific named stats (avoids returning the full prometheus dump)
server.tool(
  'get_stats',
  {
    filter: z.string().describe('Stat name prefix to filter, e.g. "cluster.my-api" or "http.ingress"')
  },
  async ({ filter }) => {
    const text = await envoyRequest(`/stats?filter=${encodeURIComponent(filter)}&format=json`);
    const data = JSON.parse(text);

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          filter,
          stats: data.stats ?? []
        }, null, 2)
      }]
    };
  }
);

// ---- force_health_drain ----
// Marks Envoy as unhealthy to drain upstream load balancers before pod termination
server.tool(
  'force_health_drain',
  {
    reason: z.string().describe('Why this instance is being drained (for logging)'),
    confirm: z.literal(true)
  },
  async ({ reason }) => {
    // POST /healthcheck/fail — causes Envoy to return 503 on its health check endpoint
    // Does NOT stop accepting traffic immediately — use /drain_listeners for that
    await envoyRequest('/healthcheck/fail', { method: 'POST' });

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          drained: true,
          reason,
          note: 'Envoy will now return 503 on health checks. Upstream load balancers will stop routing new requests within their next health check interval. Use /drain_listeners to start full graceful shutdown.'
        })
      }]
    };
  }
);

// ---- restore_health ----
server.tool(
  'restore_health',
  { confirm: z.literal(true) },
  async () => {
    await envoyRequest('/healthcheck/ok', { method: 'POST' });
    return { content: [{ type: 'text', text: JSON.stringify({ restored: true }) }] };
  }
);

Understanding health_flags in cluster status

Envoy uses a health flags bitmask to represent the health state of each endpoint. The JSON format from /clusters?format=json exposes individual boolean fields per flag. Understanding which flag caused an endpoint to be marked unhealthy is essential for debugging.

The most common flags in practice are failed_active_hc (backend health check failed) and failed_outlier_check (too many errors from real traffic). If you see failed_outlier_check, check cluster.<name>.outlier_detection.ejections_active in the stats to see how many hosts are currently ejected and ejections_total for the total ejection count since startup.

Health endpoint: /health/envoy

import express from 'express';
import { envoyRequest, envoyJsonRequest } from './envoy-client.js';

const app = express();

app.get('/health/envoy', async (_req, res) => {
  const start = Date.now();
  try {
    // Layer 1: Envoy process readiness
    const readyRes = await fetch(`${process.env.ENVOY_ADMIN_URL ?? 'http://localhost:9901'}/ready`);
    const isReady = readyRes.status === 200;
    const readyText = await readyRes.text();

    if (!isReady) {
      return res.status(503).json({
        status: 'not_ready',
        message: readyText.trim(),
        elapsed_ms: Date.now() - start
      });
    }

    // Layer 2: Cluster health summary
    const data = await envoyJsonRequest('/clusters?format=json');
    const clusters = (data.cluster_statuses ?? []) as any[];

    const clusterSummary = clusters.map(c => {
      const hosts = c.host_statuses ?? [];
      const unhealthy = hosts.filter((h: any) =>
        h.health_status?.failed_active_health_check || h.health_status?.failed_outlier_check
      );
      return {
        name: c.name,
        total: hosts.length,
        unhealthy: unhealthy.length,
        healthy: hosts.length - unhealthy.length
      };
    });

    const degradedClusters = clusterSummary.filter(c => c.unhealthy > 0);
    const latencyMs = Date.now() - start;

    res.status(degradedClusters.length > 0 ? 503 : 200).json({
      status: degradedClusters.length > 0 ? 'degraded' : 'ok',
      envoy_ready: isReady,
      total_clusters: clusters.length,
      degraded_clusters: degradedClusters.length,
      cluster_detail: degradedClusters,
      latency_ms: latencyMs
    });
  } catch (err: any) {
    res.status(503).json({
      status: 'error',
      error: err.message,
      elapsed_ms: Date.now() - start
    });
  }
});

app.listen(3001);

Graceful drain pattern for Kubernetes pods

The correct Kubernetes preStop sequence for an Envoy sidecar (or standalone Envoy pod) is: (1) mark Envoy unhealthy via POST /healthcheck/fail, (2) wait for upstream load balancers to drain, (3) call POST /drain_listeners to stop accepting new connections, (4) wait for active connections to finish. This prevents the 502 burst that happens when Kubernetes sends SIGTERM and immediately removes the pod from the Endpoints object.

// MCP tool for initiating graceful Envoy shutdown
server.tool(
  'initiate_graceful_shutdown',
  {
    wait_seconds: z.number().int().min(0).max(120).default(10)
      .describe('Seconds to wait after /healthcheck/fail before draining listeners'),
    confirm: z.literal(true)
  },
  async ({ wait_seconds }) => {
    // Step 1: Mark unhealthy — stops new requests from upstream LBs
    await envoyRequest('/healthcheck/fail', { method: 'POST' });

    // Step 2: Wait for LBs to detect unhealthy state
    await new Promise(resolve => setTimeout(resolve, wait_seconds * 1000));

    // Step 3: Drain listeners — starts graceful connection draining
    await envoyRequest('/drain_listeners', { method: 'POST' });

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          shutdown_initiated: true,
          health_fail_called: true,
          drain_listeners_called: true,
          wait_seconds,
          note: `Waited ${wait_seconds}s between health fail and listener drain. Active connections will continue until they complete or timeout.`
        })
      }]
    };
  }
);

// Kubernetes preStop hook equivalent (shell):
// lifecycle:
//   preStop:
//     exec:
//       command: ["/bin/sh", "-c", "curl -s -X POST http://localhost:9901/healthcheck/fail; sleep 10; curl -s -X POST http://localhost:9901/drain_listeners"]

Frequently asked questions

Further reading

• MCP Server Istio — VirtualService management, mTLS, and Pilot debug API tools
• MCP Server Kong Gateway — Admin API tools, upstream health checks, plugin management
• MCP Server Traefik — Router inspection, middleware management, and /ping health monitoring
• MCP Server Health Check — designing endpoints for uptime monitors
• MCP Server Kubernetes — kubectl client patterns for agent tools