Troubleshoot ToolCargo MCP connections

Check which endpoint you are connecting to

https://toolcargo.com/mcp is public discovery: it searches the directory and returns setup details without an account. It does not run the servers you find. Hosted connectors use their own URLs, such as https://toolcargo.com/mcp/site-audit, and require a scoped ToolCargo key or OAuth authorization. Copy the URL from the connector's setup page. A provider API key is not a ToolCargo key.

For a downloaded local package, check its process and client configuration instead of sending HTTP requests to ToolCargo. See local versus remote MCP setup or client connection instructions.

First: test the connection without an assistant

This ToolCargo-specific compatibility probe uses protocol version 2025-11-25 to request the Site Audit tool list. Store your scoped key in TOOLCARGO_API_KEY in your local environment first. Keep the key out of URLs, screenshots and support messages. The response includes HTTP headers and may contain an SSE event: message with JSON in its data: line.

curl -sS -i --max-time 30 https://toolcargo.com/mcp/site-audit \
  -H "Authorization: Bearer $TOOLCARGO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

• HTTP 401: check the response and WWW-Authenticate header. The credential may be missing, invalid, expired or revoked. Check the Bearer prefix; reconnect OAuth to the intended connector if necessary.
• HTTP 403 with insufficient_scope: the credential lacks the requested connector scope. Create a key with Site Audit selected for this example, or authorize that connector again.
• HTTP 403 with forbidden_origin: the request came from a browser origin ToolCargo does not accept. Use the documented client connection flow or a desktop/CLI client.
• A result containing a tool list: this request reached the connector and passed its access check. It does not prove a tool call, quota check or upstream provider request will succeed. Continue with one relevant tool call in your client and inspect its result.
• A timeout or connection error: no usable response arrived. Check network access, proxy settings and the URL before changing credentials.

To test public discovery instead, use https://toolcargo.com/mcp in this command and omit the Authorization header. That checks discovery, not access to a hosted connector. These probes do not replace a full MCP client connection and tool call.

Opening the MCP URL shows HTTP 405

An address-bar visit sends GET; MCP requests use POST. ToolCargo's public discovery endpoint returns 405 for a plain GET, while a correctly formed POST can work. Use the command above or your client's HTTP MCP connection flow. A 405 alone does not establish whether your credentials or tool calls work. The MCP Streamable HTTP specification describes the transport; client and server protocol versions still need to be compatible.

The client shows no tools

• Claude Code: run claude mcp list and /mcp inside a session. If you added the server with --scope project, it only exists in that folder.
• Check the exact URL on the chosen connector's setup page. Use /mcp/site-audit for Site Audit, not for every connector; /mcp exposes discovery tools.
• Restart the client after editing JSON configuration files; most read them only at start-up.
• For a key-based hosted connection, send Authorization: Bearer followed by your ToolCargo key. For OAuth, use the client's authorization flow rather than pasting a provider token.

OAuth sign-in fails or loops

• Sign in to ToolCargo in the same browser the client opens, then approve. Pop-up blockers can hide the window.
• If the approval page says the link is not valid, start the connection again from the client. Authorization codes expire and cannot be reused.
• Revoked the app from your dashboard? The client must reconnect; revocation is immediate.

“Monthly limit reached” or “Rate limit”

Successful metered tool results report monthly usage. Included connectors share the Site Audit allowance, which resets on the 1st (UTC); per-minute limits use fixed minute windows. Invalid input, unreachable targets and failures on our side are not counted. A returned Site Audit report for a blocked or error page still counts. Check the usage policy and your dashboard's call history for the exact outcome.

“Private or local hostnames are not fetched”

Site Audit only reaches public sites on ports 80 and 443. Staging sites behind VPNs, localhost, IP-restricted previews and password-protected pages cannot be audited. Some sites also block automated requests (HTTP 403 or a challenge page); the report will show the status the site returned.

“Blocked by the site”

The site answered with 401/403/429 or a bot-challenge page, so we could not see the real page and did not score it. If it's your client's site, allow the ToolCargoAudit user agent in the firewall or bot protection and re-run. Search engines' crawlers are often treated differently, so a block here doesn't mean Google is blocked — check with the search engine's own URL inspection tool.

The audit says the page has almost no text

Site Audit reads the HTML the server sends. A page that adds its content with JavaScript can look nearly empty in that response. Inspect the response first for a redirect, login or challenge page. If the content only appears after JavaScript runs, server-side rendering or pre-rendering can make it available in the initial HTML. Use Google Search Console's URL inspection to check Google's rendering and indexing separately; an audit result does not establish either.

Billing

• Check pricing for current checkout availability. When checkout is enabled, paid access requires ToolCargo to verify the payment with PayPal. A payment screen alone does not confirm active access; check your dashboard.
• If payment succeeded but access is missing, contact support with the purchase time. Do not send payment credentials or API keys.
• For an active recurring subscription, use the dashboard cancellation flow or PayPal automatic payments to stop renewal. A one-time purchase is not a recurring subscription.

Still stuck? Email mustafa.halawa9@gmail.com with the time of the failed call — it appears in your usage list.