Troubleshoot and resolve common MCP Gateway issues. Each issue includes the symptom, likely cause, and recommended resolution.
Common Issues
| Symptom | Likely cause | How to fix it |
|---|---|---|
404 on /v1/<name> | The provider is not attached to the appliance, or the configuration push is still pending. | Check the appliance assignment under Settings > AI Gateway > Appliances. Wait for the configuration sync to complete. |
| Tool name does not match in policy | The tool name is not in the registered tool list for the MCP provider. | Add the tool name to the Tool List in the MCP provider registration. |
OAuth2 401 from upstream | The token scope or audience does not match what the upstream server requires. | Verify the authorization server URL in the upstream metadata. Check the token scope against the server requirements. |
Rate limit 429 | The request exceeded a per-server or per-token-group rate limit. | Review the rate limit configuration under Security Platform > AI Gateway > Rate Limits. Adjust the limit or identify the source of high request volume. |
| SSE stream ends earlier than expected | A DLP, AI Guardrails, or access policy block action occurred mid-stream. | Check the DLP, AI Guardrails, and access policies for the affected MCP server. Review the SkopeIT event for the x_cs_activity and x_rs_mcp_server_name fields to identify the specific event that triggered the block. |
| MCP version warning appears in logs | The MCP client is using a spec version earlier than 2025-11-25. | Upgrade the MCP client to the MCP Streamable HTTP spec version 2025-11-25. |
| Tool list mismatch warning in logs | The tool name used in a request does not match any name in the registered tool list. | The gateway logs a warning but does not block traffic. Update the Tool List for the MCP provider to include the tool name. Go to Settings > AI Gateway > MCP Providers and edit the provider. |
Known Limitations
The following limitations apply to the current MCP Gateway release.
| Limitation | Details |
|---|---|
| No tool list auto-sync | You must manually configure tool, resource, and prompt lists in the WebUI. The gateway logs a warning when it detects a mismatch but does not block traffic. |
| No credential storage | The gateway does not store API keys or OAuth tokens for upstream servers. |
| 100 provider limit | Each tenant can register up to 100 MCP providers for the initial GA release. |
| Commercial only | MCP Gateway is not available for FedRAMP, PBMM, or China deployments in v1.5. |
| SSE partial-forward | The gateway cannot recall SSE frames forwarded before a block action. The stream closes at the point of detection. |