The MCP gateway sits between your agent and MCP servers, adding policy evaluation and audit logging to every tool call. When connections fail, the issue can be at the agent-to-gateway link, the gateway itself, or the gateway-to-server link. This guide helps you isolate and fix the problem.
Check the gateway is running. Verify the process is active and listening on the expected port:
curl http://localhost:3100/health
If the health check fails, check the gateway logs for startup errors. Common causes include port conflicts, missing environment variables, and database connection failures.
Check the transport configuration. If using stdio transport, verify that the agent's MCP client configuration points to the correct binary path. If using HTTP/SSE transport, verify the URL and port.
Check authentication. The gateway requires valid API keys. An expired or invalid key produces a 401 response. Generate a new key if needed:
npx authensor keys create --role executor --name "my-agent"
Check server registration. The gateway must know about downstream MCP servers. Verify the server configuration includes the expected servers and that their endpoints are correct.
Check tool discovery. The gateway fetches tool lists from downstream servers during initialization. If a server was unreachable during startup, its tools will be missing. Restart the gateway after ensuring all downstream servers are available.
Check policy filtering. If the agent's policy denies access to certain tools, those tools may not appear in the tool list exposed to the agent. Review the policy to confirm the expected tools are permitted.
Check downstream server responsiveness. The gateway forwards tool calls to downstream servers. If the downstream server is slow or unresponsive, the gateway request will time out.
Check network connectivity. Verify that the gateway can reach the downstream server. Firewall rules, DNS resolution, and network segmentation can block connections that worked previously.
Check request size. Very large tool parameters can cause timeouts. Review the tool call parameters for unexpectedly large payloads.
Check resource exhaustion. Memory or connection pool exhaustion causes intermittent failures under load. Monitor the gateway's resource consumption.
Check database connectivity. The gateway writes audit receipts to PostgreSQL. If the database connection pool is exhausted or the database is slow, gateway operations degrade.
Enable verbose logging during debugging and disable it once the issue is resolved. Verbose logs are valuable for diagnosis but generate significant volume in production.
Explore more guides on AI agent safety, prompt injection, and building secure systems.
View All Guides