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 tool overrides. A tool that is disabled in the connector’s overrides is not exposed.
  • 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 subprocess from starting.
  • OAuth connectors: if the outbound OAuth token expired and cannot refresh, re-authorize the connector from the console.

OAuth login does not complete

  • 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.

The build or startup fails

  • Missing secrets: the backend needs database and Redis connection strings, and the frontend needs a signing secret. A missing signing secret stops the app from starting.
  • Migrations: migrations run automatically on startup. A migration failure usually points at an unreachable or misconfigured database.

Still stuck

  • Check the activity log in the console; every tool call through the gateway is recorded with status and error details.
  • Open an issue at GitHub Issues.