Troubleshooting

Claude UI Errors

”Could not attach to MCP server”

This is the most common error in Claude Desktop and usually indicates a failure during the initial HTTP handshake.

Check the Claude Logs: Run the following command to view exactly why mcp-remote failed to connect:

tail -n 50 ~/Library/Logs/Claude/mcp*.log

Common Log Errors

HTTP 401: Unauthorized

Cause: You are either missing the x-thornguard-license header, or your license key is invalid/expired in the Qwady Dashboard.

Solution: Verify your claude_desktop_config.json includes: "--header", "x-thornguard-license: Bearer THORN-YOUR_KEY_HERE"

HTTP 403: Target URL is restricted

Cause: ThornGuard’s SSRF protection blocked your request because you are trying to proxy traffic to localhost or an internal cloud IP.

Solution: ThornGuard is designed to protect remote, web-accessible MCP servers. Ensure your x-mcp-target-url points to a valid public domain.

Error: Protected resource does not match expected origin

Cause: You are trying to connect to an upstream server that requires an interactive OAuth browser login (like GitHub Copilot). The proxy architecture prevents this specific handshake to protect against phishing.

Solution: You must decouple the authentication. Generate a Personal Access Token (PAT) for the target service and pass it directly via the config using the Authorization header. See the Quickstart for the exact JSON snippet.

HTTP 522: Connection timed out

Cause: ThornGuard successfully received your request, but the upstream server specified in your x-mcp-target-url is completely offline, firewall-blocked, or taking too long to respond.

Solution: Check the status of your destination server. Ensure it is actively running and allows incoming connections from Cloudflare’s IP ranges.

Contact Support

If you are experiencing latency issues or anomalies not covered here, please reach out to support@qwady.app and include the relevant mcp.log outputs.