connection+refused+mcp+server+kubernetes

Not specified by the original author.

TL;DR

kubectl reporting "connection refused" means the CLI cannot reach the Kubernetes API server at all. The usual causes are a wrong or stale kubeconfig context, the cluster being down or unreachable from your network, or a local proxy/port-forward that died. Verify the configured server address first, then check whether anything is actually listening there.

Error / query

kubectl "connection refused" troubleshooting

Use this skill when

• Every kubectl command fails with The connection to the server [host]:[port] was refused
• kubectl cluster-info fails but other network tools work
• A previously working kubeconfig suddenly stops connecting
• You just switched contexts and commands stopped working

Not for this skill when

• The error is Unauthorized or Forbidden (auth/RBAC problem, the connection itself works)
• The error mentions TLS certificates (expired or untrusted certs, not refused connections)
• Only one namespace or resource type fails (permissions, not connectivity)
• You are debugging pod-to-service traffic inside the cluster (that is service networking, not kubectl)

Steps

Step 1: See which server kubectl is trying to reach

kubectl config view --minify

Expected: the server: address and current context. If the address points at the wrong cluster, a dead port-forward, or YOUR_THE_HOST loopback address:[port] from a stopped proxy, you have found it.

Step 2: Confirm the current context is the one you want

kubectl config get-contexts

Expected: a list of contexts with the current one starred. If the wrong context is active, switch with kubectl config use-context [name] and retry.

Step 3: Test raw TCP connectivity to the API server

APISERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
echo "$APISERVER"
curl -sk --max-time 5 "$APISERVER/healthz"

Expected: if curl also fails to connect, the problem is network reachability (cluster down, firewall, VPN off). If curl connects but kubectl does not, suspect the kubeconfig (proxy settings, cert paths).

Step 4: Check for a dead local proxy or expired credentials file

ls -la ~/.kube/config
env | grep -i -E "proxy|kube"

Expected: the kubeconfig exists and is readable, and no stale HTTPS_PROXY is redirecting cluster traffic. A proxy env var set for office traffic is a classic cause of refused connections to internal clusters.

Step 5: Re-authenticate or regenerate the kubeconfig

kubectl config use-context [correct-context]
kubectl cluster-info

Expected: Kubernetes control plane is running at [address]. If it still fails, regenerate the kubeconfig from your cluster provider (cloud console, az aks get-credentials, aws eks update-kubeconfig, etc.) and retry.

Variant phrasings

"kubectl cannot connect to server"

Same thing. Start with step 1; the configured server address is wrong or unreachable in most cases.

"the connection to the server was refused did you specify the right host or port"

This is the full kubectl error text. It almost always means the kubeconfig points at a dead address, check context and server first.

"kubectl works on VPN but not off it"

The API server is on a private network. Either connect the VPN or expose the API through an authorized network, per your cluster's access policy.

Why it happens

kubectl is just an HTTPS client; "connection refused" happens at the TCP layer before any Kubernetes logic runs. Either nothing is listening at that address (wrong host/port, cluster down, dead port-forward) or something in the middle (firewall, missing VPN, bad proxy env) blocks the SYN. The kubeconfig is a local file, so a stale or switched context is the most common root cause.

Edge cases and pitfalls

• Kind/minikube clusters die when the VM stops; minikube status or the docker daemon state tells you fast.
• Multiple kubeconfig files merge via KUBECONFIG; a stale entry in a second file can shadow the right one.
• Some corporate proxies intercept and refuse non-proxied HTTPS; add the cluster IP to NO_PROXY.
• Port-forwards (kubectl proxy, ssh tunnels) die silently; the refused connection is on your machine, not the cluster.
• After a cluster upgrade the API server address or CA can change; regenerate credentials rather than editing the file by hand.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_v9OaRFdSqIg0PMmGDe8OTw

Resolved from the public thread: https://vectle.com/posts/pst_v9OaRFdSqIg0PMmGDe8OTw

Thread query: kubectl "connection refused" troubleshooting

TL;DR: kubectl reporting "connection refused" means the CLI cannot reach the Kubernetes API server at all. The usual causes are a wrong or stale kubeconfig context, the cluster being down or unreachable from your network, or a local proxy/port-forward that died. Verify the configured server address first, then check whether anything is actually listening there.

Not specified by the original author.

With no kubeconfig loaded, kubectl falls back to a server on the local loopback at port 8080 - which is not a real cluster. This almost always means your kubeconfig is missing or KUBECONFIG points nowhere. Fetch a fresh config from your provider (EKS, GKE, AKS) or export KUBECONFIG to the right file, then retry.

The error

The connection to the server YOUR_HOST:8080 was refused - did you specify the right host or port?

What to do

1. Confirm nothing is loaded:

kubectl config view --minify

Expected: Empty clusters/contexts/users, or an error - no config is active.

2. Find the gap:

echo $KUBECONFIG
ls -la ~/.kube/config

Expected: Shows the unset variable or the missing file.

3. Rebuild the config, e.g.:

aws eks --region [region] update-kubeconfig --name [cluster]

(GKE: gcloud container clusters get-credentials [cluster] --region [region]; AKS: az aks get-credentials ...) Expected: Context added to ~/.kube/config.

4. Verify:

kubectl get nodes

Expected: Node list, no connection error.

When this applies

• the exact YOUR_HOST:8080 connection refused message
• fresh shells where KUBECONFIG was set in another shell
• sudo runs that lose the user's env and home

When it does NOT apply

• connection refused on a real cluster IP or hostname (cluster or network is down)
• certificate or auth errors (config loaded, creds bad)

Works with

all kubectl versions

The connection to the server [real-host]:6443 was refused

Same words, real address: the cluster itself is unreachable. Check the API server and network instead of the kubeconfig.

Why it happens

kubectl's default server is the loopback on port 8080 when no kubeconfig provides a cluster entry. Nothing listens there on a normal machine, so the OS refuses the connection.

Edge cases

• Running kubectl with sudo uses root's home and env, so your user's ~/.kube/config and KUBECONFIG vanish - either run as your user or pass --kubeconfig explicitly.
• On a kubeadm-built cluster, copying /etc/kubernetes/admin.conf to ~/.kube/config as your user fixes this permanently.

Resolved from

gh:tmatin100/troubleshoot (aws/eks troubleshooting doc) - https://github.com/tmatin100/troubleshoot/blob/HEAD/aws/eks/The%20connection%20to%20the%20server%20localhost:8080%20was%20refused.md

Asked: kubectl get pods fails with The connection to the server was refused, did you specify the right host or port, on a fresh EKS workstation. Verified answer: No kubeconfig was loaded; regenerate it with aws eks update-kubeconfig so kubectl stops falling back to the loopback default. Source: https://github.com/tmatin100/troubleshoot/blob/HEAD/aws/eks/The%20connection%20to%20the%20server%20localhost:8080%20was%20refused.md (thread gh:tmatin100/troubleshoot (aws/eks troubleshooting doc)). Tool: kubectl.

Not specified by the original author.

TL;DR: ECONNREFUSED means nothing is listening where the MCP server is looking. Start MySQL, then make sure MYSQL_HOST and MYSQL_PORT in the client config match where it actually listens. The defaults (YOUR_HOST:3306) are wrong for Docker and remote setups.

Error: connect ECONNREFUSED the loopback address:3306

Fix it

1. Check MySQL is running:

# Linux
sudo systemctl status mysql
# macOS (Homebrew)
brew services list
# Docker
docker ps | grep mysql

2. Check what it listens on:

sudo netstat -tlnp | grep 3306

Expected: a line showing mysqld on 3306 (or your configured port).

3. Set the real address in the client config env block. Docker on the host: host.YOUR_HOST. Docker Compose service: the service name. Remote: the hostname or IP.

{
  "env": {
    "MYSQL_HOST": "host.YOUR_HOST",
    "MYSQL_PORT": "3306"
  }
}

4. Restart the MCP client.

   Expected: the refused error is gone. Next failure, if any, will be auth, which is progress.

When to use this

• The error is ECONNREFUSED mentioning the MySQL host and port.
• mysql -h [host] from a terminal also fails to connect.

When NOT to use this

• The error is ER_ACCESS_DENIED_ERROR. The server is reachable; credentials are wrong.
• The error is a timeout (ETIMEDOUT). That is firewall or routing, not a refused connection.

Compatibility

• benborla/mcp-server-mysql.
• MySQL 5.7, 8.x, MariaDB, in Docker or on the host.

Why it happens

Connection refused is the OS telling you the SYN packet arrived but no process accepted it. Either MySQL is down, or it is up but bound to a different interface or port than the config says. MCP defaults assume a local MySQL on 3306, which breaks the moment MySQL lives in Docker or on another machine.

Edge cases

• MySQL in Docker without a published port is unreachable from the host. Add -p 3306:3306.
• bind-address = the loopback address in my.cnf blocks remote connections even when the port is open. Set it to the all-interfaces address for remote access (with proper grants).
• Skip-networking enabled means TCP is off entirely. The MCP server needs TCP; use a socket only if the server supports it.

ECONNREFUSED is the standard TCP connection-refused error when the MySQL server is not running or not listening at the configured host and port, documented in MySQL troubleshooting guides with the fix of starting the MySQL service and verifying the host and port. The benborla/mcp-server-mysql server reads MYSQLHOST and MYSQLPORT from the environment, defaulting to YOUR_HOST:3306, so a MySQL running elsewhere or on a different port produces this exact error. Source: https://github.com/benborla/mcp-server-mysql