Troubleshooting

This guide helps you diagnose and resolve common issues with MCP Gateway.

Enabling Debug Logging

To get more detailed logs, set the LOG_LEVEL environment variable to debug:

apiVersion: mcp-gateway.ohcs.io/v1alpha1
kind: MCPGateway
metadata:
  name: my-gateway
spec:
  domain: mcp.example.com
  env:
  - name: LOG_LEVEL
    value: debug

Viewing Logs

Operator Logs

The operator manages CRDs and creates Kubernetes resources:

kubectl logs -l app.kubernetes.io/name=mcp-gateway-operator -n mcp-gateway-system

Gateway Logs

The gateway handles MCP request routing:

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

To follow logs in real-time:

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

Common Issues

Gateway Not Routing Requests

Symptoms: Requests return 404 or connection refused.

Possible causes:

1. ConfigMap not synced - The operator may not have updated the gateway ConfigMap yet.

   # Check if the ConfigMap exists and has content
   kubectl get configmap -l app.kubernetes.io/managed-by=mcp-gateway-operator

2. MCPRemoteServer/MCPContainerServer not ready - Check the status of your server resources:

   kubectl get mcpremoteservers,mcpcontainerservers

3. Path mismatch - Ensure the request path matches the spec.path in your server resource.

TLS Certificate Issues

Symptoms: Browser shows certificate errors, or curl fails with SSL errors.

Debugging steps:

1. Check if the certificate Secret exists:

   kubectl get secret -l app.kubernetes.io/managed-by=mcp-gateway-operator

2. If using cert-manager, check the Certificate resource:

   kubectl get certificates
   kubectl describe certificate <name>

3. Check cert-manager logs for issuance errors:

   kubectl logs -l app=cert-manager -n cert-manager

Authentication Failures

Symptoms: Requests return 401 Unauthorized.

Debugging steps:

1. Verify the auth token Secret exists and has the correct key:

   kubectl get secret <auth-secret-name> -o yaml

2. Ensure the MCPGateway references the correct Secret:

   kubectl get mcpgateway <name> -o yaml | grep -A2 authSecretRef

3. Confirm the client is sending the correct header:

   curl -v -H "Authorization: Bearer <token>" https://mcp.example.com/

Container Server Not Responding

Symptoms: Requests to MCPContainerServer paths timeout or fail.

Debugging steps:

1. Check if the container pod is running:

   kubectl get pods -l app.kubernetes.io/managed-by=mcp-gateway-operator

2. Check pod logs for errors:

   kubectl logs <pod-name>

3. For STDIO transport, verify the container accepts stdin:

   kubectl attach -it <pod-name>

4. For HTTP transport, verify the container is listening on the expected port:

   kubectl exec <pod-name> -- netstat -tlnp

Ingress Not Working

Symptoms: External requests don’t reach the gateway.

Debugging steps:

1. Check Ingress resource status:

   kubectl get ingress
   kubectl describe ingress <gateway-name>

2. Verify the ingress controller is running:

   kubectl get pods -n ingress-nginx  # or your ingress namespace

3. Check if the Service has endpoints:

   kubectl get endpoints <gateway-name>

Getting Help

If you’re still experiencing issues:

1. Check the GitLab Issues for known problems
2. Enable debug logging and collect relevant logs
3. Open a new issue with your configuration and logs