Troubleshoot MCP

Troubleshoot a connection

Symptom	What to check
Claude web says your account was authorized but the server returned an error	Check the saved URL and use Claude’s published identity as described in client setup. If the error persists, share the error reference and time of the attempt with support. A successful authorization alone does not verify a tool connection.
HTTP `307` redirect to an `http://` URL	Use `https://agents.labs.bandwidth.com/api/v1/mcp/`. Do not replace the configured URL with an HTTP redirect target. If the redirect persists with this exact URL, share the response details with support.
`Needs authentication` or HTTP `401`	Run your client’s login command and complete Labs consent. Use OAuth for this exact MCP URL; API keys and REST tokens are not accepted.
The client reports unsupported client registration or an unknown CIMD option	Update the client to a version with CIMD support. Follow client setup without a manually configured client ID, secret, or API-key header.
HTTP `403` or a tool permission error	Sign in to Agent Builder once, select a workspace you belong to, and check your workspace role. Authorize with the same Labs account.
The server is configured but tools are missing	In Claude Code or Codex, start a new session and inspect `/mcp`. In Claude web, enable the connector for the conversation and inspect its tools. A saved configuration alone does not verify authentication or a successful tool call.
Claude says agent listing is unavailable after switching workspace	Switching does not remove tools from the server’s catalog. Search for `list_agents` or `list_workflows`, check that the listing tool is enabled in the connector, and refresh discovery if needed. Do not substitute numeric-ID scans through `list_agent_calls`.
Agents are missing or belong to a different workspace	Call `get_current_workspace`. Use `list_workspaces` and `switch_workspace` to select the intended group, then call `list_agents` again. Check whether another client changed your account’s selection. An empty result is not necessarily a connection failure.
DNS, TLS, or connection timeout	For CLI clients, confirm that your machine can reach the MCP URL and the Labs sign-in site over HTTPS using the checks below. Claude web requires access from Anthropic’s cloud; local curl checks do not verify that path.

Claude can load connectors on demand, so a tool missing from the assistant’s current context does not by itself show that the server removed it. In Claude web, you can select + → Connectors → Tool access → Always available for the conversation while diagnosing discovery. See Claude’s tool access guide. If listing is still unavailable, inspect the connector’s actual tool list and share the tool error and time of the attempt with support. For SSH sessions or a browser that does not open, run the relevant command in an interactive terminal:

Claude Code
Codex

claude mcp login bandwidth_agents --no-browser

codex mcp login bandwidth_agents \
  --scopes voai \
  --oauth-client-registration cimd \
  --no-browser

Open the displayed authorization URL in your browser, finish Labs sign-in and consent, then paste the full callback URL into the waiting terminal prompt. If the callback page cannot load, you can still copy its URL from the address bar. Treat that URL as a credential and do not share it in chat or logs.

Check reachability with curl

This initialization request deliberately sends no credentials:

curl --silent --show-error --include --max-time 20 \
  'https://agents.labs.bandwidth.com/api/v1/mcp/' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"cli-connection-test","version":"1.0.0"}}}'

Expect HTTP 401, a WWW-Authenticate header containing the OAuth discovery URL, and this response body:

{"detail":"Labs OAuth bearer token required"}

Read the public discovery metadata with:

curl --silent --show-error --fail-with-body --max-time 20 \
  'https://agents.labs.bandwidth.com/.well-known/oauth-protected-resource/api/v1/mcp/'

Expect HTTP 200 with JSON containing resource, authorization_servers, and scopes_supported, including voai. These checks verify endpoint reachability and OAuth discovery. Complete client login and call list_workflows to verify authenticated workspace access. To connect a running voice agent to an external MCP server, see MCP tools for voice agents.

Get started

Use MCP

Workspaces

Agents

Calls and outcomes

Phone numbers

Resources

Authoring guidance

Documentation

Troubleshoot a connection

Check reachability with curl

​Troubleshoot a connection

​Sign in without automatically opening a browser

​Check reachability with curl

Troubleshoot a connection

Sign in without automatically opening a browser

Check reachability with curl