MSP Claude Plugins

Troubleshooting

Common issues and fixes for the WYRE MCP Gateway. If your issue isn't listed here, check the vendor health dashboard for upstream outages. Prefer to have Claude triage it for you? Use the wyre-gateway-troubleshooting skill.

"Invalid OAuth error response: Unexpected token '<'"

This error means the OAuth discovery or token endpoint returned HTML instead of JSON — typically a Cloudflare error page (404, 502, or 520) rather than the gateway's response.

Causes

  • The gateway is being deployed (brief downtime during container restart)
  • A vendor MCP container is down and Cloudflare is returning its default error page
  • DNS or routing misconfiguration

Fix

  1. Wait 1–2 minutes and try again (deployments typically complete within 60 seconds)
  2. Check /health — if it returns {"status":"ok"}, the gateway is running
  3. Check /health/vendors to see if a specific vendor is down
  4. If the issue persists, restart Claude Desktop and try again

"Connection refused" on OAuth callback

During OAuth, mcp-remote opens a temporary local HTTP server (e.g., localhost:26873) to receive the OAuth callback. If too many OAuth flows run simultaneously, the listener can time out before the browser redirects back — resulting in "connection refused" on the callback URL.

Causes

  • Multiple per-vendor entries — each vendor triggers its own OAuth flow on startup; with 5+ vendors, the listeners race and time out
  • The browser took too long to complete the OAuth flow (manual login, 2FA, etc.)
  • A firewall or antivirus is blocking localhost connections

Fix

  1. Use the unified endpoint — replace all per-vendor mcp-remote entries with a single entry pointing to https://mcp.wyre.ai/v1/mcp. This means one OAuth flow instead of many. See the Gateway setup guide.
  2. If using per-vendor endpoints, add them one at a time — connect one vendor, restart Claude Desktop, then add the next
  3. Kill any stale mcp-remote processes: pkill -f mcp-remote
  4. Restart Claude Desktop

"Failed to reconnect" / stale sessions

After a gateway deployment or container restart, existing MCP sessions become invalid. The mcp-remote bridge may show "failed to reconnect" errors or hang indefinitely.

Fix

  1. Kill all mcp-remote processes: 
    pkill -f mcp-remote
  2. Restart Claude Desktop (or restart Claude Code's MCP connection with /mcp)
  3. The client will establish a fresh session with the gateway on the next request

This is expected after deployments. The gateway deploys new revisions with zero-downtime traffic switching, but mcp-remote's persistent connections don't automatically reconnect to the new revision.

Vendor shows DOWN on /health/vendors

The /health/vendors endpoint monitors all vendor MCP containers. If a vendor shows "status": "down", the underlying vendor container is unreachable.

Causes

  • The vendor's MCP container is restarting after a deployment
  • The vendor's upstream API is experiencing an outage
  • A container crashed and is being restarted by the orchestrator

Fix

  1. Wait 2–5 minutes — containers typically auto-recover
  2. Check the consecutiveFailures count in the health response — if it's climbing, the issue is ongoing
  3. Other vendors on the unified endpoint continue to work normally — only the affected vendor's tools will be unavailable

Connected vendor's tools don't appear

If you've added credentials for a vendor but its tools don't show up in Claude:

  1. Verify your credentials are saved at mcp.wyre.ai — log in and check the credentials page
  2. Fully quit and reopen Claude Desktop (Cmd+Q on macOS, then relaunch). Claude registers the gateway's tool catalog at the moment its MCP client connects and does not refresh while a session is live — adding a new vendor in the Wyre dashboard will not push tools into a running Claude session. In Claude Code, use /mcp and reconnect the gateway entry.
  3. The unified endpoint only lists tools for vendors where you have valid credentials — if credentials are expired or invalid, that vendor is silently skipped
  4. If using org/team credentials, ensure you have the correct role and the vendor's tools are in your team's allowlist

"Failed to update tool access" on the Tool Allowlists page

When you toggle which vendor tools are available for admins or members and click Save, the gateway returns a generic alert: "Failed to update tool access." The most common cause is a permissions mismatch.

Cause

Saving or clearing a tool allowlist requires the org owner role. Admins can open the Tool Allowlists page and see every vendor with all tools checked (the "allow all" default), but any Save or Reset action returns 403 Requires owner role or higher — which the UI surfaces as the generic alert.

Fix

  1. Confirm which user is the org owner: Organization → Members. The owner has the highest privilege level and is typically the user who created the organization.
  2. If you are not the owner, ask them to make the allowlist change for you, or have them transfer ownership.
  3. If you are signed in as the owner and still see this error, contact hello@wyre.ai with your org name and the vendor you were editing.

Note: every vendor's tools appearing as "checked" on a fresh org is expected. With no allowlist saved, the gateway permits every tool for that role; the checkboxes reflect the effective default, not a stored configuration.

Triage with Claude (the wyre-gateway-troubleshooting skill)

If you'd rather not walk through this page yourself, the WYRE skill set includes a wyre-gateway-troubleshooting skill that teaches Claude how to diagnose the same issues described above — missing tools, "Failed to update tool access" errors, OAuth failures, expired credentials, and the request flow through the gateway.

Install the shared skills plugin

/plugin marketplace add wyre-technology/msp-claude-plugins
/plugin install shared-skills

Run these in Claude Code. The skill becomes available immediately — no restart needed. Already have the marketplace added? Just run /plugin install shared-skills.

Trigger phrases

Once installed, Claude will pick up the skill automatically when you describe a gateway problem. Phrases that reliably trigger it:

  • "My WYRE gateway tools aren't showing up in Claude"
  • "I get 'Failed to update tool access' when I try to save"
  • "OAuth is failing on mcp.wyre.ai"
  • "Why is my IT Glue (or Autotask, CIPP, etc.) connection not working?"
  • "Help me troubleshoot the WYRE gateway"

What the skill does

The skill walks Claude through the five-layer request path (Claude → mcp-remote → gateway → vendor container → vendor API), asks you targeted questions to localize the failure, and gives you the fix specific to your symptom. For permission-related errors it identifies whether the user is the org owner; for missing tools it confirms the credentials are saved and points you at the Cmd+Q-and-reopen step. If the issue requires WYRE support, the skill prepares the information we need (org name, vendor slug, exact error, timestamp) so the handoff is fast.

Source: shared/skills/wyre-gateway-troubleshooting in the msp-claude-plugins repository.

Was this page helpful? See our roadmap.

Give Feedback Request a Feature Report a Problem