Troubleshooting

This page collects the most common issues and how to resolve them.

A client cannot connect to a Virtual MCP

Check the endpoint URL. It must be the Virtual MCP endpoint, https://<host>/api/v1/mcp/{virtual-mcp-id}, not the console URL.
Check the credentials. For API key auth, the Authorization header must be Bearer brg_live_sk_... with a key scoped to that Virtual MCP. A key scoped to a different Virtual MCP is rejected.
Confirm the Virtual MCP is enabled and has at least one connector.

A tool is missing from the client

Confirm the connector is connected. A connector that failed to start or authenticate contributes no tools.
Check the Virtual MCP’s Tools tab. A tool with a disabled badge there is switched off for that Virtual MCP, so clients cannot list or call it. Switch it back on to expose it again. Other Virtual MCPs that use the same connector keep their own settings.
Remember namespacing. Aggregated tools appear as {connector}.{tool}. If two connectors export the same tool name, both remain distinct under their connector prefixes.

A connector shows as disconnected

Remote connectors: for Streamable HTTP (http) or legacy HTTP+SSE compatibility (sse), verify the upstream URL is reachable and any required headers (including auth) are set. A 401 from the upstream usually means a missing or expired credential.
Local (stdio) connectors: confirm the package name and runner (npx or uvx) are correct. A typo in the package name prevents the connector from starting.
“Package … is blocked by the BridgeMCP platform”: the package is on the platform blocklist, so the connector cannot be saved with it or started. Change the connector to a different package or version, or contact support. See package policy.
“Connector … was disabled by the BridgeMCP platform”: BridgeMCP disabled the connector. Enabling it in the console does not lift this. Contact support to have it reviewed.
“Your organization is running the maximum of N stdio connectors on this server”: your organization reached its limit of concurrently running stdio connectors on one server. Disable or remove a stdio connector you no longer use, or wait for idle connectors to be released, then retry.
An error saying the server is at capacity, or has no room for another npx or uvx connector: the server’s shared capacity for stdio connectors is in use. Disable an unused stdio connector, or retry once idle connectors and running jobs are released.
A stdio connector cannot reach an internal service: custom stdio connectors have no access to private or internal networks. Expose the service on a public endpoint the connector can reach.
OAuth connectors: if the outbound OAuth token expired and cannot refresh, re-authorize the connector from the console.

Consent page loops back to login: the browser session may not be authenticated. Sign in to the console first, then retry the authorization.
Redirect mismatch: for the CLI loopback flow, the redirect must be an exact 127.0.0.1 loopback address, not localhost.

A modern MCP request returns a protocol error

-32020 HeaderMismatch: the MCP-Protocol-Version, Mcp-Method, or required Mcp-Name header is missing or does not exactly match the JSON-RPC body. Update the MCP client or SDK rather than adding a version suffix to the endpoint URL. If you maintain the client, generate the mirrored headers from the same request object as the body.
-32021 MissingRequiredClientCapability: a tool returned an input_required result for elicitation, sampling, or roots input that this request did not declare. Use a client that supports and declares the requested capability, or choose a tool flow that does not require it. Retrying without changing capabilities returns the same error.
-32022 UnsupportedProtocolVersion: the request named a revision BridgeMCP does not support. Let the client negotiate one of the five revisions from 2024-11-05 through 2026-07-28; keep the existing /api/v1/mcp/{virtual-mcp-id} URL unchanged.

If a tool-list subscription disconnects, reconnect and call tools/list again. Subscription streams have no resume token or replay, so missed changes are not redelivered.

Still stuck