> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents.labs.bandwidth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot MCP

> Resolve sign-in, discovery, workspace, and connection problems.

## 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](https://docs.agents.labs.bandwidth.com/mcp/clients.md). 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](https://docs.agents.labs.bandwidth.com/mcp/clients.md) 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](https://support.claude.com/en/articles/13730515-manage-claude-s-tool-access). If listing is still unavailable, inspect the connector's actual tool list and share the tool error and time of the attempt with support.

### Sign in without automatically opening a browser

For SSH sessions or a browser that does not open, run the relevant command in an interactive terminal:

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp login bandwidth_agents --no-browser
> ```

> [tab] Codex
>
> ```bash theme={null}
> 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:

```bash theme={null}
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:

```json theme={null}
{"detail":"Labs OAuth bearer token required"}
```

Read the public discovery metadata with:

```bash theme={null}
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](https://docs.agents.labs.bandwidth.com/voice-agent/tools/mcp-tool.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.