Skip to main content

Documentation Index

Fetch the complete documentation index at: https://qwady.wiki/llms.txt

Use this file to discover all available pages before exploring further.

​
Start With Client Logs

If a connection fails, check the client-side MCP logs first.
  • Claude Desktop: review the local Claude MCP logs: 
    tail -n 50 ~/Library/Logs/Claude/mcp*.log
  • Other clients: inspect the client or editor’s MCP connection/output logs for the failing request, then correlate the failure with any x-thornguard-log-id or x-thornguard-trace-id values returned by ThornGuard.

​
Common Errors

Cause: Your ThornGuard credential is missing or invalid, or the current activation ID / activation proof pair is missing or stale.Solution: Verify the client is sending a valid ThornGuard bearer value either in x-thornguard-license or Authorization, plus the current activation ID in x-thornguard-activation-id and the matching activation proof in x-thornguard-activation-proof.
Cause: The client reached a protected URL such as https://thorns.qwady.app/mcp/42, but that saved connection does not exist for the current license scope anymore.Solution: Re-sync the profile from the CLI or dashboard, or switch the client back to the legacy /mcp plus x-mcp-target-url path while you repair the saved connection inventory.
Cause: The client is still using the legacy /mcp route but did not include the upstream target header ThornGuard needs for that compatibility path.Solution: Either add x-mcp-target-url: https://your-upstream-mcp-server/mcp to the protected server config, or migrate the client to a managed route such as /mcp/:connection-id.
Cause: ThornGuard’s SSRF protection blocked your request because you are trying to proxy traffic to localhost, a metadata IP, or a hostname that resolves to a private address. Solution: ThornGuard is designed to proxy publicly reachable MCP servers. Ensure your saved connection target or x-mcp-target-url points to a valid public HTTPS target.
Cause: Your client sent an Origin header that does not match the allowed origin list for this deployment. Solution: Make requests from an approved origin or update the deployment allowlist. This mainly affects browser-based HTTP clients.
Cause: You are trying to connect to an upstream server that requires an interactive OAuth browser login or a native protected-resource flow that your current setup path is not completing. Solution: Use a non-interactive upstream credential and forward it via x-upstream-auth, or complete the auth flow outside the MCP connection and use the resulting token. See Quickstart for the exact JSON snippet.
Cause: ThornGuard rate limiting blocked the request because the current per-license minute window was exceeded.Solution: Wait for the Retry-After window to pass or reduce the request rate from the client.
Cause: The client reused a ThornGuard session ID against the wrong connection, activation, or actor binding.Solution: Let the CLI or launcher mint a fresh x-thornguard-session-id, or stop reusing a session across unrelated managed connections.
Cause: ThornGuard detected schema drift for a tool and the current connection policy escalated that change into review_required or quarantine.Solution: Open the Platform page, review the drift state for the tool, then re-pin the current definition if the change is expected.
Cause: ThornGuard successfully received your request, but the upstream server in the saved connection record or legacy 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.
Cause: ThornGuard itself hit an internal error before the request could complete.Solution: Capture any x-thornguard-log-id or x-thornguard-trace-id values, note the exact time of the error, and contact support with the failing client logs.

​
Secret Exposure in Local Logs

When you use a local bridge tool such as mcp-remote, CLI-passed headers may appear in local logs or process listings before traffic reaches ThornGuard. ThornGuard sanitizes secrets in its own audit trail and webhook deliveries, but it cannot sanitize logs emitted locally by client tools.

​
Contact Support

If you are experiencing latency issues or anomalies not covered here, please reach out to [email protected] and include the relevant mcp.log outputs plus any x-thornguard-log-id or x-thornguard-trace-id values returned by the proxy.