MCP Server Integration
Let external MCP clients manage port forwards through kftray's built-in MCP server.
kftray's Model Context Protocol (MCP) server lets compatible clients browse Kubernetes resources, manage port forwards and change saved configs.
Enabling
Open Settings in kftray.
Find the MCP Server section.
Turn it on and set the port. The default is 3000.
The server runs in the background as part of kftray. It stops when kftray closes and starts again on the next launch if you left it enabled.
| Setting | Default | Description |
|---|---|---|
| Enabled | false | Whether the MCP server starts with the app |
| Port | 3000 | Port the server listens on |
Connecting a client
Point an MCP client at:
http://localhost:3000/mcpClients that read server definitions from a config file usually need an entry like this:
{
"mcpServers": {
"kftray": {
"url": "http://localhost:3000/mcp"
}
}
}The file location depends on the client, so check its documentation.
To check that the server is running:
curl http://localhost:3000/healthThe server listens on 127.0.0.1 only and uses these routes:
| Route | Purpose |
|---|---|
POST /mcp | JSON-RPC requests from the client |
GET /mcp | Server-sent events stream |
DELETE /mcp | Ends a session |
GET /health | Health check |
What it can do
The server exposes 16 tools in three areas.
Clients can browse clusters, control port forwards and manage the same saved configs as the desktop and terminal apps. The examples show tool calls for each task.
Shared state
The MCP server, desktop app and terminal app share one database, configs.db in the configuration directory (~/.kftray by default). Each interface shows configs and forwards created through the others.
Examples
Tool reference
Cluster browsing
| Tool | Required args | Returns |
|---|---|---|
list_kube_contexts | context names | |
list_namespaces | context | namespace names |
list_services | context, namespace | service names |
list_pods | context, namespace | pods with name, status and labels |
list_ports | context, namespace, service | ports with name, number, target port and protocol |
Every tool accepts an optional kubeconfig parameter. list_pods also accepts label_selector.
Port-forward control
| Tool | Required args | Returns |
|---|---|---|
start_port_forward | config_id, or context + namespace + remote_port for a new forward | local port, remote port, config ID |
stop_port_forward | config_id | service name, namespace |
stop_all_port_forwards | count of stopped forwards | |
list_active_port_forwards | list of active forwards with config ID, service, namespace, ports, protocol, alias |
Without config_id, a new forward also needs service for a service workload or target (a label selector) for a pod workload. It also accepts:
local_portandprotocol(tcporudp).workload_type(service,podorproxy).kubeconfigandalias.
Configuration management
| Tool | Required args | Returns |
|---|---|---|
list_configs | configs with ID, alias, service, namespace, ports, protocol. Takes an optional filters list | |
get_config | config_id | full config details |
create_config | context, namespace, remote_port, plus service, target or remote_address for a service, pod or proxy workload | config ID |
update_config | config_id | success status |
delete_config | config_id | success status |
export_configs | all configs as JSON | |
import_configs | configs_json | success status |
list_configs takes filters, a list of conditions that must all match. Each condition is field=value[,value...], or a bare field for "is set". The fields are context, namespace, kubeconfig, workload_type, protocol and tag:<key>. For example, ["tag:team=payments"], ["namespace=api,web"] or ["tag:pinned"].
create_config and update_config take a tags object. Tag keys use lowercase letters, digits, ., _, - and /, and an empty string value makes a key-only tag. update_config replaces the whole tag map, and {} removes all tags. See tags, filters and group by.
Security
Local only by default
The server binds to 127.0.0.1, so only processes on the same machine can reach it.
The MCP server uses the same kubeconfig credentials as the rest of kftray. It doesn't store or send credentials separately.