MCP Servers

Connect k8s-autopilot to external tools using the Model Context Protocol

k8s-autopilot natively supports the Model Context Protocol (MCP). MCP lets you connect external tool providers — Kubernetes cluster inspectors, CI/CD platforms, monitoring systems, and cloud APIs — directly into the agent without writing custom code. Each MCP server exposes a set of tools that the agent can discover and call like native functions.

k8s-autopilot ships with 11 built-in MCP servers, but the system is completely open: you can connect any third-party or internal MCP server through the UI or configuration files.

Add an MCP Server

From the Settings UI

Go to Settings → MCP Servers and click + Add Server. Enter the server name, command, arguments, and environment variables. The server is saved to the configuration database and made available immediately — no restart needed.

From a Config File

MCP servers can also be configured in .mcp.json files using the standard format:

{
  "mcpServers": {
    "my-database": {
      "command": "npx",
      "args": ["-y", "@my-org/db-mcp-server"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    },
    "my-cloud": {
      "command": "uvx",
      "args": ["cloud-mcp-server"],
      "env": {
        "API_KEY": "${MY_CLOUD_API_KEY}"
      }
    }
  }
}

Each server entry defines:

Field	Type	What It Does
`command`	string	Executable to launch (`npx`, `python`, `uvx`, `docker`, or a binary name)
`args`	list	Arguments passed to the server process
`env`	object	Environment variables for the server process
`url`	string	URL for HTTP/SSE transport (use instead of `command` for remote servers)
`transport`	string	Transport type: `stdio` (default), `http`, or `sse`
`headers`	object	HTTP headers for remote transports (e.g. auth tokens)
`disabled_tools`	list	Glob patterns for tools to exclude (e.g. `["delete_", "drop_"]`)
`allowed_tools`	list	Glob patterns for tools to include (only matching tools are loaded)

Environment Variable Expansion

Config values support ${VAR} and ${VAR:-default} syntax (POSIX :- semantics). The :- form falls back to the default when the variable is unset or empty:

{
  "env": {
    "PROMETHEUS_URL": "${PROMETHEUS_BASE_URL:-http://localhost:9090}",
    "API_TOKEN": "${MY_SECRET_TOKEN}"
  }
}

If a ${VAR} reference has no default and the variable is unset in the environment, k8s-autopilot rejects the config with a clear error message rather than passing through an empty string.

Where Configs Are Loaded From

k8s-autopilot discovers MCP server configs from multiple locations and merges them together. The database is the source of truth — file-based configs are auto-seeded into the database on first discovery:

Priority	Location	Source Label
1	Database (Settings UI)	`db`
2	Global user configs `~/.agents/.mcp.json` or `~/.agents/mcp.json` `~/.k8s_autopilot/.mcp.json` or `~/.k8s_autopilot/mcp.json`	`global`
3	Project-level configs `.mcp.json`, `mcp.json`, `.k8s_autopilot/.mcp.json` in project root	`project`
4	Plugin configs `plugins/{name}/.mcp.json` for non-agent plugins	`plugin:{name}`
5	Installed plugin configs Plugins installed from marketplace that bundle MCP servers	`plugin:{name}`

Operator Isolation

Operator-bundled MCP servers (in built_in_subagents/) are not loaded globally. They are strictly isolated — each operator connects to its own MCP servers only when invoked.

How Tools Are Named

When k8s-autopilot connects to an MCP server, it discovers all available tools and registers them with a namespaced name:

mcp__{server}__{tool}

For example, a tool get_pods from server kubernetes becomes:

mcp__kubernetes__get_pods

This prevents name collisions when multiple servers expose tools with the same name.

Transports

stdio (Default & Recommended)

The MCP server runs as a local subprocess of k8s-autopilot, communicating via standard input/output (stdin/stdout). No network ports or firewall configurations are needed.

{
  "command": "npx",
  "args": ["-y", "kubernetes-mcp-server@latest"]
}

HTTP

For Docker Compose, remote deployments, or shared MCP servers across teams, use HTTP transport:

{
  "url": "http://my-mcp-server:8080",
  "transport": "http",
  "headers": {
    "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
  }
}

You can also override built-in operator servers to HTTP transport using the MCP_SERVERS environment variable (a JSON array):

MCP_SERVERS='[
  {"name": "helm_mcp_server", "url": "http://helm-mcp:8080", "transport": "http"},
  {"name": "prometheus-mcp-server", "url": "http://prom-mcp:8080", "transport": "http"}
]'

SSE (Server-Sent Events)

For servers that use the SSE streaming protocol:

{
  "url": "http://my-server:8080/sse",
  "transport": "sse"
}

If transport is not specified, k8s-autopilot auto-detects it: if url contains "sse" it uses SSE; if url is present it uses HTTP; otherwise it defaults to stdio.

Trust and Security

Trust Levels & SHA-256 Fingerprinting

Not all MCP configs are equally trusted. Configs committed to a shared Git repository could be contributed by anyone, so k8s-autopilot uses SHA-256 fingerprinting to gate project-level configs:

Global configs (~/.agents/, ~/.k8s_autopilot/) — Always trusted. You control these directly on your machine.
Database configs (Settings UI) — Always trusted. You added them explicitly in the console.
Built-in operator configs — Always trusted. They ship verified with k8s-autopilot.
Project-level configs (.mcp.json in project root) — Require explicit approval on first use. k8s-autopilot records your trust decision by hashing the file's SHA-256 fingerprint. If the file is modified in Git, the agent asks for confirmation again.

Semantic Tool Profiling

When an MCP server connects, k8s-autopilot automatically analyzes every tool it exposes and classifies it into a security tier. This happens at registration time with zero runtime overhead:

Tier	Classification	Behavior	Examples
Tier 1 — Read-only	Strictly idempotent inspection	Runs automatically	`get_pods`, `query_metrics`, `list_releases`, `search_charts`
Tier 2 — Low-impact	Reversible or transient mutations	Runs with light confirmation	`dry_run_install`, `add_label`, `annotate`
Tier 3 — Mutating	Modifies live infrastructure	Gated by HITL approval	`install_chart`, `scale_deployment`, `apply_manifest`, `sync_app`
Tier 4 — Destructive	Irreversible deletion or eviction	Blocked without explicit allowlist	`delete_namespace`, `uninstall_release`, `drain_node`, `drop_database`

The profiler checks both MCP tool annotations (the standard readOnlyHint and destructiveHint fields) and heuristic verb analysis (scanning tool names for patterns like get_, list_, delete_, uninstall_). Annotations always take precedence over heuristics.

Headless Mode Safety

When k8s-autopilot runs without a web UI (headless mode, CI/CD pipelines, Slack integration), the HeadlessMCPGuardMiddleware automatically blocks all Tier 3 and Tier 4 MCP tool calls that lack a coherent readOnlyHint=true annotation. This prevents unattended mutations from running in autonomous environments.

Tool Filtering

You can restrict which tools are exposed by any server using glob patterns:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubernetes-mcp-server@latest"],
      "allowed_tools": ["get_*", "list_*", "describe_*"],
      "disabled_tools": ["delete_*", "exec_*"]
    }
  }
}

allowed_tools — Only matching tools are loaded (allowlist).
disabled_tools — Matching tools are excluded (denylist).
If both are specified, disabled_tools is checked first.

Just-In-Time (JIT) Connection Lifecycle

MCP connections follow a Just-In-Time pattern for operator-bundled servers:

You ask a question routed to an operator
Operator's CompiledSubAgent wrapper opens the MCP connection
Operator executes its tools via MCP
Connection closes immediately after the operator completes

This prevents idle processes and memory leaks when many servers are registered but only a subset is used per conversation. Global (non-operator) MCP servers stay connected for the duration of the session.

MCP Timeout Settings

Variable	Default	What It Controls
`MCP_TIMEOUT`	`30`	Per-tool execution timeout in seconds
`MCP_TIMEOUT_TOTAL`	`600`	Total operation timeout in seconds
`MCP_TIMEOUT_CONNECT`	`300`	Server connection / startup timeout in seconds
`MCP_DEFAULT_TRANSPORT`	`sse`	Default transport for new servers: `sse`, `stdio`, or `http`

Enabling and Disabling Servers

You can enable or disable any MCP server from the Settings → MCP Servers panel in the UI. Disabled servers are not connected during startup, and their tools are hidden from the agent.

From a config file, use the enabled field:

{
  "mcpServers": {
    "my-server": {
      "command": "my-mcp-server",
      "enabled": false
    }
  }
}

Built-in MCP Servers Reference

Server Name	Operator	Tools	Key Capabilities
`helm-mcp-server`	Helm Operator	22	Install, upgrade, rollback, uninstall, dry-run, value schema validation
`argocd-mcp-server`	App Operator	29	Application onboarding, synchronization, rollback, health audits
`argo-rollout-mcp-server`	App Operator	18	Canary promotions, blue-green cutovers, `AnalysisTemplate` monitoring
`traefik-mcp-server`	App Operator	11	IngressRoute configuration, weighted traffic splitting, middleware
`kubernetes-mcp-server`	K8s Operator	32	Workloads, pod logs & exec, events, node diagnostics, RBAC, contexts
`prometheus-mcp-server`	Observability	28	PromQL execution, ServiceMonitors, alerting & recording rules, cardinality
`alertmanager-mcp-server`	Observability	14	Active alert triage, silences, receiver testing, notification routing
`opentelemetry-mcp-server`	Observability	19	Collector CRD provisioning, auto-instrumentation injection, sampling
`loki-mcp-server`	Observability	9	LogQL log streams, label discovery, trace-to-log correlation
`tempo-mcp-server`	Observability	16	TraceQL distributed tracing queries, RED metrics, waterfall timelines
`github-mcp-server`	Helm / Core	12	Repository management, Helm chart branch commits, PR creation

Next Steps

Configuration Reference — Full settings reference including MCP environment variables.
Operators & Sub-agents — Which operators use which MCP servers.
Approval Modes & Governance — How the approval system works with MCP tool tiers.
Plugins & Marketplace — How plugins bundle custom MCP servers.

Add an MCP Server​

From the Settings UI​

From a Config File​

Environment Variable Expansion​

Where Configs Are Loaded From​

How Tools Are Named​

Transports​

stdio (Default & Recommended)​

HTTP​

SSE (Server-Sent Events)​

Trust and Security​

Trust Levels & SHA-256 Fingerprinting​

Semantic Tool Profiling​

Headless Mode Safety​

Tool Filtering​

Just-In-Time (JIT) Connection Lifecycle​

MCP Timeout Settings​

Enabling and Disabling Servers​

Built-in MCP Servers Reference​

Next Steps​