Chapter 4. Troubleshoot MCP gateway external MCP servers

Procedure

1. If you are seeing errors such as 502 Bad Gateway and 403 Forbidden, check the ServiceEntry CR by running the following command:

   $ oc get serviceentry -n <namespace>

   Replace with the <namespace> where the ServiceEntry CR is applied.

   1. If the command returns an empty list, create a ServiceEntry CR to allow egress.

2. For detailed troubleshooting, such as to checks ports and the TLS setting, examine the ServiceEntry CR activity by running the following command:

   $ oc describe serviceentry <se_name> -n <namespace>

   • Replace with the <se_name> with the name the ServiceEntry CR.
   • Replace with the <namespace> where the ServiceEntry CR is applied.
3. Verify that ServiceEntry CR hosts values are exact matches external hostname values.

4. If you are seeing TLS errors, verify that a DestinationRule CR exists by running the following command:

   $ oc get destinationrule -n <namespace>

   Replace with the <namespace> where the DestinationRule CR is applied.

   1. If the previous command returns No resources found in <namespace> namespace, create a DestinationRule CR.
   2. Ensure that DestinationRule CR host values exactly match ServiceEntry CR host values.
   3. Check the TLS configuration in DestinationRule CR.

5. For detailed troubleshooting of actual connection details, such as encryption, load balancing, and connection pooling, examine the DestinationRule CR by running the following command:

   $ oc describe destinationrule <dr_name> -n <namespace>

   • Replace with the <dr_name> with the name the DestinationRule CR.

   • Replace with the <namespace> where the DestinationRule CR is applied.

     1. Ensure that your network egress policies allow external traffic from the pod.

6. Test the DNS resolution by running the following command:

   $ oc run -it --rm debug --image=<image_path/name> --restart=Never -- \
     nslookup <external_hostname>

   • Replace <image_path/name> with the path to your application image.
   • Replace <external_hostname> with your external MCP server hostname parameter value.

7. Test the external connectivity by running the following command:

   $ oc run -it --rm debug --image=<image_path/name> --restart=Never -- \
     curl -v https://<external_hostname_url>

   • Replace <image_path/name> with the path to your application image.
   • Replace <external_hostname_url> with your external MCP server URL.
8. Verify that the HTTPRoute CR backendRef value is configured with the correct external hostname.
9. Ensure that the HTTPRoute CR has the URLRewrite filter applied to rewrite to the external hostname.

Procedure

1. Check that a Secret custom resource (CR) exists and that it has the correct label by running the following command:

   $ oc get secret <secret_name> -n <namespace> --show-labels

   • Replace <secret_name> with the name of your Secret CR.
   • Replace <namespace> with the namespace where your Secret CR is applied.

2. Verify the Secret CR contents by running the following command:

   $ oc get secret <secret_name> -n <namespace> -o yaml

   • Replace <secret_name> with the name of your Secret CR.
   • Replace <namespace> with the namespace where your Secret CR is applied.

3. Check the MCPServerRegistration CR credentialRef parameter value by running the following command:

   $ oc get mcpsr <mcpsr_name> -n <namespace> -o yaml | grep -A 3 credentialRef

   • Replace <mcpsr_name> with the name of your MCPServerRegistration CR.
   • Replace <namespace> with the namespace where your MCPServerRegistration CR is applied.
4. Ensure that the Secret CR has the label mcp.kuadrant.io/secret: "true".
5. Verify that the Secret CR data key matches the credentialRef.key in the MCPServerRegistration CR.
6. Check the credential format.
7. Verify that the credential you are using has the necessary permissions for the external service.

8. Check the MCP gateway broker component logs for credential errors by running the following command:

   $ oc logs -n <mcp_system> deployment/mcp-gateway | grep -i auth

   Replace <mcp_system> with the name of your MCP gateway deployment.