Skip to content
ConduitConduit

Troubleshooting

Each section heading below is a symptom you would actually see — a client behavior, a dashboard state, or a verbatim error in a tool result. Search by copying a unique phrase from what you observed.

Conduit is a hosted gateway: you connect an MCP client to it and sign in once — you do not install Conduit. Most issues are one of three things: the client is not actually connected, your role is not granted the vendor or tool, or a vendor credential is missing or expired. The sections below are ordered roughly that way.

Fast first check: https://conduit.wyre.ai/status shows Gateway, Database, and Vendor Integrations at a glance, so you can tell a Conduit-side problem from a single vendor outage before digging further. For your own organization’s specific vendors, the dashboard’s Vendor Health view (see Vendor health) shows per-vendor status, latency, and errors scoped to what you’ve connected.

Source IP rejected? Conduit’s outbound calls leave from one static address, 20.242.40.128. Allowlist it on the vendor firewall or API-key IP restriction. See Static egress IP.

Running a Tunnel instead? Its boot-time failures are a separate list — see Tunnels — troubleshooting.

No tools appear in your AI client after you connect

Section titled “No tools appear in your AI client after you connect”

The client connected and signed in, but no Conduit tools show up.

Three common causes:

  • Your client cached the tool list at connect time. Most clients read the tool catalog once when the MCP session opens and do not refresh it live — so a vendor connected (or newly granted) after you signed in will not appear until you reconnect. Conduit automatically asks a still-connected client to re-fetch its tool list when it detects it served a stale one (for example, right after a deploy while vendor containers restart) — most of the time this resolves on its own within a minute or two with no action from you. If it doesn’t, fully quit and reopen Claude Desktop (Cmd+Q on macOS, not just closing the window), or run /mcp and reconnect the server entry in Claude Code.
  • Your organization has no vendors connected yet. Conduit only exposes tools for vendors your organization has connected. Confirm at least one vendor shows a green status on the Connections page (/org/catalog). See Vendor connections.
  • Your access grant restricts them. Vendor and tool access is deny-by-default. Your admin controls this per connection, from that vendor’s Access editor on /org/catalog — the Everyone default plus any per-member/per-team exceptions. Ask your admin to check your effective access using the editor’s Check a member’s access panel, which shows exactly why a vendor or tool is or isn’t available to you. See Permissions and Managing access.

Also check: the client actually finished the OAuth sign-in (see The browser sign-in never finishes) — a client that never completed auth shows zero tools, not an error.

Claude Code: add fails, or the URL is treated as a command

Section titled “Claude Code: add fails, or the URL is treated as a command”

claude mcp add errors out, or Claude Code tries to run your endpoint URL as a local program instead of connecting to it.

Fix: include --transport http, and put the flag before the server name:

Terminal window
claude mcp add --transport http conduit https://conduit.wyre.ai/v1/mcp

Without --transport http, Claude Code treats the URL as a local command and the add fails. Flags come before the server name. See Connecting an AI client.

The browser sign-in never finishes

Section titled “The browser sign-in never finishes”

The first connection opens a browser to sign in, but it hangs or never returns you to a connected state.

Fix:

  • Allow pop-ups for the sign-in window, then retry the connection. A blocked pop-up is the usual cause.
  • Complete the sign-in fully (email/password or Microsoft / Entra ID) before returning to your client. The token is cached and refreshed after the first success — you sign in once, not every session.

For how the first connection works, see First connection.

OAuth fails with Unexpected token '<'

Section titled “OAuth fails with Unexpected token '<'”

Your client reports an error like Invalid OAuth error response: Unexpected token '<'. This means the OAuth discovery or token request got back HTML instead of JSON — usually an error page, not Conduit’s actual response.

Causes:

  • Conduit is mid-deploy and briefly restarting.
  • A vendor MCP server is down and the edge is serving a default error page.
  • A DNS or routing problem is sending your request somewhere other than Conduit.

Fix:

  1. Wait a minute or two, then retry — deploys usually finish quickly.
  2. Check https://conduit.wyre.ai/status. If Gateway and Database both show healthy, Conduit is running and the problem is elsewhere.
  3. Check the dashboard’s Vendor Health view to see whether a specific vendor you’ve connected is down.
  4. If it persists, restart your client and retry.

OAuth callback fails with Connection refused

Section titled “OAuth callback fails with Connection refused”

During sign-in, the mcp-remote bridge opens a short-lived local listener (for example, localhost:26873) to catch the OAuth callback. If the browser redirects back after that listener has already timed out, you get Connection refused on the callback URL.

Causes:

  • Sign-in took longer than the listener’s timeout — a manual login step or a two-factor prompt got in the way.
  • A firewall or antivirus tool blocked the localhost connection.
  • Multiple sign-in attempts were started close together and their local listeners collided (rare — mainly a risk if your client config points at more than one Conduit endpoint at once; the unified endpoint avoids this by design).

Fix:

  1. Clear any stale bridge processes, then retry:

    Terminal window
    pkill -f mcp-remote

  2. Restart your client and complete the browser sign-in promptly.

  3. Confirm your client is configured with a single https://conduit.wyre.ai/v1/mcp entry rather than one per vendor — see Connecting an AI client.

Your client asks for an API key and never opens a sign-in browser

Section titled “Your client asks for an API key and never opens a sign-in browser”

A client’s native remote-MCP setup expects you to paste an API key or bearer token, and it never opens the OAuth sign-in browser.

Why: people connect with OAuth 2.1 + PKCE — a browser sign-in — so for an interactive client there is no API key to paste.

Fix: connect that client through the mcp-remote bridge instead — it performs the OAuth flow for any client. Client config formats and remote-OAuth support change between releases, so confirm against your installed version.

Unless nobody is there to sign in. An unattended agent that cannot run a browser flow at all connects as a service account with a static agent key instead. That is a long-lived secret in a config file, so reach for it only when OAuth genuinely isn’t possible — not to skip a sign-in that a person could do once.

A tool call comes back with a permissions error

Section titled “A tool call comes back with a permissions error”

The client is connected and the tool is visible, but a call returns a permissions/authorization error.

Fix: you are not granted that vendor or tool. Vendor and tool access is deny-by-default and controlled per connection by your admin, via that vendor’s Access editor on /org/catalog (the Everyone default plus per-member/ per-team exceptions, and — for specific tools — a hand-picked selection within a Read/Write/Delete/Admin group). Owners always have full access. Ask your admin to check the Check a member’s access panel on the connection’s Access editor, which shows the exact rule that produced the denial, then grant the vendor or tool there. See Permissions.

A tool call returns no credentials for vendor

Section titled “A tool call returns no credentials for vendor”

The tool ran, but Conduit has no credential it can resolve for that vendor on your behalf.

Fix: no credential is configured at any scope you can resolve. A vendor credential can live at personal, team, or organization scope. Connect the vendor at the organization scope (/org/catalog) so every technician shares it, or confirm you are in a team that has one. The audit log records every tool call with its status code, which helps confirm whether a failure is auth, the vendor, or the tool. The user column is a name (or email, or service-account name) — hover it for the stable id if you need to match a specific account. See Vendor connections.

A connected vendor shows red / unhealthy

Section titled “A connected vendor shows red / unhealthy”

A vendor that was green now shows a red or unhealthy status, and its tools fail.

Fix:

  • Re-connect the vendor at the matching scope. Conduit ran a health check when the credential was saved; a red status usually means the stored credential is now invalid (rotated, revoked, or expired upstream). Re-connect at the same scope (org-level at /org/catalog) — Conduit encrypts the new credential and uses it immediately, overwriting the old one.
  • Check the dashboard’s Vendor Health view directly to confirm the status and see every vendor your organization has connected in one place.
  • For what each health state means and how checks run, see Vendor health.

An OAuth vendor (Xero, QuickBooks Online, Calendly) stopped working

Section titled “An OAuth vendor (Xero, QuickBooks Online, Calendly) stopped working”

An OAuth-based vendor was connected and working, then started failing.

Why: for OAuth vendors, Conduit stores the access and refresh tokens and refreshes them automatically — so a sudden failure usually means the refresh token was revoked upstream: a password change, an app uninstall, or withdrawn admin consent.

Fix: re-run the OAuth connect flow for that vendor from /org/catalog. See Vendor connections.

The connection worked, then stopped

Section titled “The connection worked, then stopped”

Tools were working in a client, then calls began failing or the tools disappeared.

Fix: your session may have been revoked, or a vendor credential changed. Reconnect the client (it re-runs the OAuth sign-in):

  • In Claude Desktop: fully quit (Cmd+Q on macOS, not just closing the window) and reopen.
  • In Claude Code: run /mcp and reconnect the Conduit server entry.
  • Using the mcp-remote bridge: clear any stale bridge processes first — pkill -f mcp-remote — then restart your client.

This is also the expected behavior right after a Conduit deploy: Conduit switches revisions without downtime, but a long-lived mcp-remote connection doesn’t automatically follow to the new revision, so it needs the reconnect above. If a specific vendor is the one failing (not every vendor), check its status on the Connections page instead — that’s a credential problem, not a session problem. If reconnecting doesn’t help, contact your admin.

Microsoft Copilot Studio: the connector’s authorization is rejected

Section titled “Microsoft Copilot Studio: the connector’s authorization is rejected”

A Copilot Studio custom connector fails authorization against Conduit when set up like a Claude-style OAuth client.

Why: Power Platform’s Generic OAuth 2.0 does not send PKCE, so Conduit’s authorization endpoint rejects it. Copilot Studio is the one supported client that does not use the browser OAuth flow.

Fix: use the service-client (API Key) path documented in Connecting Microsoft Copilot Studio, which passes Authorization: Bearer <token> — an OAuth 2.0 client-credentials access token — rather than the PKCE browser flow.

Which endpoint should I use — mcp.wyre.ai or conduit.wyre.ai?

Section titled “Which endpoint should I use — mcp.wyre.ai or conduit.wyre.ai?”

This applies to the US service only. Australian and UK organizations use their own region’s address, au.conduit.wyre.ai or uk.conduit.wyre.ai.

On the US service, both work against the same gateway. For new setups use conduit.wyre.ai/v1/mcp (over HTTPS), the recommended endpoint. Clients already configured against mcp.wyre.ai/v1/mcp keep working unchanged (same gateway, same auth, no migration needed). The /v1/mcp path is the unified endpoint that exposes every vendor your organization has connected.

A vendor rejects the call because of the source IP

Section titled “A vendor rejects the call because of the source IP”

IT Glue, on-prem ConnectWise Automate, and other vendors can refuse API calls that do not come from an allowlisted address. The failure often looks like an HTTP 403, a connection timeout, or an “IP not allowed” message from the vendor — not a Conduit permissions error.

Fix: allowlist Conduit’s static egress IP, 20.242.40.128. IT Glue usually sets this on the API key; on-prem products set it on the server firewall. See Static egress IP. If the system is not reachable from the internet at all, use a tunnel instead of opening inbound access.

Still stuck

Section titled “Still stuck”

Before contacting support, check the two diagnostic sources that separate a Conduit-side problem from a client or vendor one:

  • https://conduit.wyre.ai/status — Conduit’s own liveness, plus the dashboard’s Vendor Health view for status scoped to what your organization has connected.
  • The dashboard’s audit log — a per-request record of tool calls and their outcomes, including status codes.

If neither explains it, contact your admin (or your WYRE contact if you operate the deployment yourself) with:

  • The verbatim error from your AI client or the failing tool result.
  • Which client and version you are using (Claude Code, Claude Desktop via mcp-remote, Cursor, Copilot Studio, …).
  • Your organization and, if relevant, the vendor that is failing.
  • Whether other vendors work — this isolates an auth/session problem from a single-vendor credential problem.

See Getting support for every way to reach the WYRE support team directly.