Troubleshooting - cturner8/kube-mcp GitHub Wiki

This page covers common issues and their solutions when running kube-mcp.

Check the pod logs for errors:

kubectl logs -l app.kubernetes.io/name=kube-mcp

Common causes:

Check readiness probe failures:

kubectl describe pod -l app.kubernetes.io/name=kube-mcp

The server exposes a /health endpoint. If probes are failing, verify the container port matches your service configuration.

Verify OIDC discovery is accessible:

curl https://<your-oidc-issuer>/.well-known/openid-configuration

Check the Protected Resource Metadata endpoint:

curl https://<your-mcp-url>/.well-known/oauth-protected-resource

Common causes:

If your MCP client isn't prompting for authentication:

1. Verify the client supports OAuth/OIDC authentication
2. Check the client supports HTTP transport
3. Ensure the server URL is correct and accessible from your machine

Example: pods is forbidden: User "system:serviceaccount:..." cannot list resource "pods"

This indicates Kubernetes RBAC is blocking access. Verify the ServiceAccount permissions:

# Check what the ServiceAccount can access
kubectl auth can-i list pods --as=system:serviceaccount:<namespace>:kube-mcp

# View the ClusterRole rules
kubectl get clusterrole kube-mcp -o yaml

Solutions:

• Add the missing resource to rbac.rules in your values.yaml
• Ensure the resource's API group is included (e.g., apps for Deployments)

See RBAC for detailed configuration.

Secrets and ConfigMaps are intentionally excluded from default RBAC. To enable:

1. Add secrets/configmaps to rbac.rules
2. Remove them from mcp.tools.disallowed (they're disabled by default)

Possible causes:

1. Tool is disallowed - Check mcp.tools.disallowed doesn't include the tool
2. Allowlist in use - If using mcp.tools.allowed, the tool must be explicitly listed
3. Client caching - Restart your MCP client to refresh the tool list

Possible causes:

1. No resources exist - Verify resources exist in the specified namespace
2. RBAC restrictions - The ServiceAccount may lack permission (check logs)
3. Namespace not specified - Some tools require a namespace argument

Check ingress is configured:

kubectl get ingress -l app.kubernetes.io/name=kube-mcp

For testing without ingress, use port-forwarding:

kubectl port-forward svc/kube-mcp 9000:9000

Then configure your MCP client to use http://localhost:9000.

If accessing kube-mcp from a browser and seeing CORS errors:

mcp:
  allowedOrigins: "https://your-app.example.com"

Multiple origins can be specified as comma-separated values.

Increase log verbosity to diagnose issues:

mcp:
  logging:
    level: "debug"

Then view logs:

kubectl logs -l app.kubernetes.io/name=kube-mcp -f

To debug authentication issues, decode your JWT token at jwt.io and verify:

• iss matches mcp.oidc.issuerUrl
• aud matches mcp.oidc.clientId
• exp is in the future
• Required scopes are present in scope or scp claim

• GitHub Issues: cturner8/kube-mcp/issues
• Known Limitations: Limitations