Chapter 5. Troubleshoot MCP gateway auth

Procedure

1. Retrieve the JSON object that lists the security requirements for your backend MCP server by running the following command:

   $ curl https://<mcp_hostname>/.well-known/oauth-protected-resource

   Replace <mcp_hostname> with the name of the host for your MCP server.

   Example output

   {
     "resource_name": "MCP Server",
     "resource": "https://mcp.example.com/mcp",
     "authorization_servers": [
       "https://auth.provider.com/realms/mcp"
     ],
     "bearer_methods_supported": ["header"],
     "scopes_supported": [
       "basic",
       "groups",
       "roles",
       "profile"
     ]
   }

2. Check that your associated HTTPRoute CR includes a path for /.well-known/oauth-protected-resource by running the following command:

   $ oc get httproute <route_name> -n <mcp_system> -o json | jq -r '.spec.rules[].matches[].path.value | select(. == "/.well-known/oauth-protected-resource")'

   • Replace <route_name> with the associated HTTPRoute CR.
   • Replace <mcp_system> with the name of your MCP gateway deployment.
3. If there is no output, your HTTPRoute CR does not have a path for /.well-known/oauth-protected-resource. You must add one.

4. Check the specific AuthPolicy CR configuration by running the following command:

   $ oc describe authpolicy <authn_name> -n <namespace>

   • Replace <authn_name> with the name of your AuthPolicy CR.
   • Replace <namespace> with the namespace where your AuthPolicy CR is applied.

5. Check that you excluded all /.well-known/ paths from your AuthPolicy CR by trying to reach the endpoint without any credentials by using the following command:

   $ curl -o /dev/null -s -w "%{https_code}\n" https://<mcp_hostname>/.well-known/oauth-protected-resource

   Replace <mcp_hostname> with the name of the host for your MCP server.

   Note

   The following codes are examples of possible outputs:

   • 200: Means that the exclusion exists and matches.
   • 401: Means that your AuthPolicy CR is still demanding a token for this path. The exclusion is either not present or not working.
   • 404: The exclusion might be present and working, but the HTTPRoute CR does not point to that path or to a valid backend.

6. Optional. Check all MCP broker component environment variables by running the following command:

   $ oc get deployment <mcp_gateway> -n <mcp_system> -o yaml | grep -A 10 env

   • Replace <mcp_gateway> with the name of your MCP gateway deployment.
   • Replace <mcp_system> with the namespace where your MCP gateway deployment is applied.
7. Verify that the MCP broker component pod restarted after any environment variable changes.

Procedure

1. Check your AuthPolicy custom resource (CR) authorization rules by running the following command:

   $ oc get authpolicy <policy_name> -n <namespace> -o yaml | grep -A 20 authorization

   • Replace <policy_name> with the name of your AuthPolicy CR.
   • Replace <namespace> `with the namespace where your `AuthPolicy CR is applied.

2. When your authorization checks are not enforced, first check your AuthPolicy CR status by running the following command:

   $ oc describe authpolicy <policy_name> -n <namespace>

   • Replace <policy_name> with the name of your AuthPolicy CR.
   • Replace <namespace> `with the namespace where your `AuthPolicy CR is applied.

3. Next, verify your AuthPolicy CR targets the correct resource by running the following command:

   $ oc get authpolicy <policy_name> -n <namespace> -o yaml | grep -A 5 targetRef

   • Replace <policy_name> with the name of your AuthPolicy CR.
   • Replace <namespace> `with the namespace where your `AuthPolicy CR is applied.

4. Ensure that your AuthPolicy CR targetRef matches your Gateway object name and namespace by running the following command:

   $ echo "--- AuthPolicy Targets ---" && \
   oc get authpolicy -n <mcp_system> -o jsonpath='{range .items[*]}{.metadata.name}{"\t targets -> \t"}{.spec.targetRef.kind}{"/"}{.spec.targetRef.name}{"\n"}{end}' && \
   echo "--- Actual Gateways ---" && \
   oc get gateway -n <mcp_system> -o custom-columns=NAME:.metadata.name

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

5. If your AuthPolicy CR and your Gateway object are in different namespaces, you must either move the AuthPolicy CR into the same namespace as the Gateway object, or target the HTTPRoute CR instead.

6. Check that your AuthPolicy CR sectionName matches your Gateway object listener name.

   $ oc describe authpolicy <auth_policy_name> -n <mcp_system>

   • Replace <auth_policy_name> with the name of your AuthPolicy CR.
   • Replace <mcp_system> with the name of your MCP gateway deployment.
7. Examine the Status block for an entry about your listener. If the sectionName is wrong, the policy shows "Accepted", but the policy does not affect the intended traffic path.