--- title: Troubleshooting and FAQ description: Fixes for Queue CallBack MCP server connection, tool and data problems, answers to common questions, and how to reach support. status: Stable last_updated: 2026-11-05 canonical: https://queuecallback.com/docs/mcp/troubleshooting --- # Troubleshooting and FAQ This page fixes common problems with the Queue CallBack MCP server (`https://mcp.queuecallback.com/mcp`), such as refused connections, sign-in problems in Claude and ChatGPT, missing tools, masked numbers and results saved to a file, and answers common questions. Find what you see in the table below. > For AI agents: this page is also available as Markdown at `https://queuecallback.com/docs/mcp/troubleshooting.md`. The whole MCP documentation in one file: https://queuecallback.com/docs/llms-full.txt | What you see | Section | |---|---| | `Failed to connect`, HTTP 401, or `invalid_token` | [Cannot connect: 401 invalid_token](#cannot-connect-401-invalid_token) | | The client opens a browser, or says the server needs authentication | [The client opens a browser to sign in](#the-client-opens-a-browser-to-sign-in) | | Claude or ChatGPT keeps asking you to sign in, or the sign-in fails | [Sign-in from Claude or ChatGPT fails or repeats](#sign-in-from-claude-or-chatgpt-fails-or-repeats) | | A signed-in connection cannot make a change, or answers `insufficient_scope` | [A change fails after sign-in](#a-change-fails-after-sign-in) | | A signed-in connection acts in the wrong organization | [Signed in to the wrong organization](#signed-in-to-the-wrong-organization) | | HTTP 403 with `mcp_disabled` | [403 mcp_disabled on every request](#403-mcp_disabled-on-every-request) | | Connected, but a tool you expected is not listed, or a call to it is refused with a code such as `insufficient_scope` or `writes_disabled` | [A tool is missing](#a-tool-is-missing) | | 415, 400 or 405 from curl or your own code | [415, 400 or 405 from your own HTTP requests](#415-400-or-405-from-your-own-http-requests) | | HTTP 429, `rate_limited`, `concurrency_limited` or `queue_write_limited` | [429: too many requests](#429-too-many-requests) | | `confirm_refused` or `confirm_required` | [confirm_refused when making a change](#confirm_refused-when-making-a-change) | | Claude Code says a tool result was saved to a file | [Claude Code saves a result to a file](#claude-code-saves-a-result-to-a-file) | | Caller numbers look like `+*******4567` | [Caller numbers are masked](#caller-numbers-are-masked) | | The IVR flow tools disappeared, or `custom_ivr_not_enabled` | [IVR tools are gone after a plan change](#ivr-tools-are-gone-after-a-plan-change) | | Callers ask for callbacks, but the callbacks are not dialed, or a queue shows `ringcentral_connection` `needs_reconnect` or `not_connected` | [Callbacks are not dialing](#callbacks-are-not-dialing) | | Any other error code | The code tables in [Errors and limits](/docs/mcp/errors#tool-errors) | ## Start here: three checks If a client fails to connect to the Queue CallBack MCP server, look for these first, in this order. In Claude Code, `claude mcp list` shows the first one: | What you see | Fix | |---|---| | `claude mcp list` warns that `QCB_API_KEY` is missing, or the variable check in [Cannot connect](#cannot-connect-401-invalid_token) prints `(0 characters)` | The variable is not set in the environment the client started from. Set it, then start the client again from that environment. | | 401 `invalid_token` | The key did not arrive or was refused. For a new key, the cause is most often the variable, the quotes or the copy; see the ranked causes in [Cannot connect](#cannot-connect-401-invalid_token). | | 403 `mcp_disabled` | The organization's API access is off. See [403 mcp_disabled on every request](#403-mcp_disabled-on-every-request). | These three checks show whether a problem is in the Queue CallBack MCP server, in your API key, or in your client's setup. None of them changes anything. 1. Check that the service is up: ```bash curl -sS https://mcp.queuecallback.com/healthz ``` The answer contains `"status":"ok"` while the service runs. `backend` reports the last known state of the Queue CallBack API. 2. Test your API key outside the client. This request sends the key from the environment variable `QCB_API_KEY` with an `initialize` message, the handshake that most MCP clients send first. It reads no data and changes nothing: ```bash curl -sS -i https://mcp.queuecallback.com/mcp \ -H "Authorization: Bearer $QCB_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"key-check","version":"1"}}}' ``` In PowerShell 7 or later: ```powershell $headers = @{ Authorization = "Bearer $env:QCB_API_KEY"; Accept = "application/json, text/event-stream" } $body = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"key-check","version":"1"}}}' $r = Invoke-WebRequest -Method Post -Uri "https://mcp.queuecallback.com/mcp" -Headers $headers -ContentType "application/json" -Body $body -SkipHttpErrorCheck $r.StatusCode; $r.Headers["X-Request-Id"]; $r.Content ``` | Status | `error.data.code` | Meaning | |---|---|---| | 200 | none | The key works. The problem is in the client's setup. | | 401 | `invalid_token` | The key did not arrive or was refused. See [Cannot connect](#cannot-connect-401-invalid_token). | | 403 | `mcp_disabled` | The organization's API access is off. See [403 mcp_disabled](#403-mcp_disabled-on-every-request). | | 429 | `concurrency_limited` or `rate_limited` | Too many requests. See [429](#429-too-many-requests). | | 502 or 503 | for example `backend_unreachable` | A temporary problem on the Queue CallBack side. Retry after the `Retry-After` seconds, or after about 5 seconds when there is none. | 3. Once the client connects, ask it to call `get_me`. The answer shows which organization, role and scopes the connection has (see [Check the connection](/docs/mcp/connect#check-the-connection)). The fields that matter here, with placeholder values: ```json { "actor_type": "api_key", "api_key": { "id": "00000000-0000-0000-0000-000000000000", "name": "Claude Code - reporting", "prefix": "qcb_sk", "last4": "a1b2", "created_at": "2026-11-01T09:00:00Z", "expires_at": "2027-01-30T09:00:00Z", "minted_by": "...a1b2c3" }, "organization_id": "11111111-1111-1111-1111-111111111111", "role": "org_admin", "scopes": ["callbacks:read", "org:read", "queues:read", "reports:read"], "pii_allowed": false, "custom_ivr_enabled": false, "ivr_reporting_enabled": false, "delegation": null, "user_id": "apikey:00000000-0000-0000-0000-000000000000" } ``` `scopes` lists the scopes that take effect, not every scope the key was given. `pii_allowed` says whether caller numbers are unmasked. `custom_ivr_enabled` says whether the IVR flow tools are available, and `ivr_reporting_enabled` whether the IVR call reports are. Every answer from the Queue CallBack MCP server itself carries an `X-Request-Id` header. Keep it when you contact support. Answers that the web server in front makes on its own (404, 413 and its per-address 429) do not carry it. ## Cannot connect: 401 invalid_token The Queue CallBack MCP server answers HTTP 401 when no usable API key or sign-in token arrived. The server does not say which check failed. The causes below are about API keys; for a sign-in from Claude or ChatGPT, see [Sign-in from Claude or ChatGPT fails or repeats](#sign-in-from-claude-or-chatgpt-fails-or-repeats). For every cause below except two `Authorization` headers, the answer is: ```json { "jsonrpc": "2.0", "id": null, "error": { "code": -32001, "message": "The credential is missing, malformed or unknown, or the API key has expired, been revoked or been suspended (a key is suspended while the admin who created it is deactivated or no longer in the organization), or the sign-in has ended. Send a valid Queue CallBack API key as Authorization: Bearer , or sign in again; an organization admin sees each key's status on the portal's API keys page.", "data": { "code": "invalid_token" } } } ``` For a newly created key, check these causes first, most likely first: `QCB_API_KEY` is not set where the client started; the server was added with double quotes; the key was copied wrong; the word `Bearer` is missing; the variable's name starts with `ANTHROPIC_`. A Status of Expired, Revoked or Suspended is rare for a new key. Find the cause: 1. Check the environment variable in the same terminal or app environment that starts your client. These commands print only the first 7 characters and the length, never the key: ```bash printf '%s (%s characters)\n' "${QCB_API_KEY:0:7}" "${#QCB_API_KEY}" ``` ```powershell $k = $env:QCB_API_KEY; if ($k) { "{0} ({1} characters)" -f $k.Substring(0, [Math]::Min(7, $k.Length)), $k.Length } else { "QCB_API_KEY is not set" } ``` A complete key prints `qcb_sk_ (79 characters)`. 2. Check the key in the portal. Open **Settings**, then **Manage API keys**, and find the key by name. The **Status** column shows Active, Suspended, Expired or Revoked. Turn on **Show revoked and expired keys** to see the last two. 3. Run the key test in [Start here](#start-here-three-checks). If it answers 200, the key is fine and the client is not sending it. | Cause | How to tell | Fix | |---|---|---| | `QCB_API_KEY` is not set where the client started | The bash check prints `(0 characters)`; the PowerShell check prints `QCB_API_KEY is not set` | Set the variable, then restart the client from that environment. Desktop apps such as Cursor, VS Code and Claude Desktop read variables only when they start. On macOS, an app opened from the Dock may not see variables set in `~/.zshrc`. Depending on the client, the header then goes out empty (`Bearer ` with nothing after it), or the server entry reports a configuration error. | | The server was added in Claude Code with the key expanded while the variable was empty | You ran `claude mcp add ... --header "Authorization: Bearer $QCB_API_KEY"` in double quotes before setting the variable | The shell stored an empty header. Run `claude mcp remove queuecallback --scope user` (leave out `--scope` if you added it for one project) and add it again with single quotes as shown in [Claude Code](/docs/mcp/connect#claude-code). | | The server was added in Claude Code with double quotes while the variable held a key | `claude mcp get queuecallback` does not show `${QCB_API_KEY}` in the `Authorization` header | An old key is stored in plain text in `~/.claude.json` and goes stale at every rotation. Run `claude mcp remove queuecallback --scope user` (leave out `--scope` if you added it for one project), add it again with single quotes as in [Claude Code](/docs/mcp/connect#claude-code), and rotate the key if the file was shared. | | The key is mistyped, cut off, or was copied with quotes or spaces | The variable check shows another start or another length | The portal shows a key only once. If you no longer have it, rotate the key: the new key has the same name and scopes and is shown once. Store it again. Rotating stops the old key at once, so update every client that uses it. | | The header lacks the word `Bearer` | The header value is the bare key | Send exactly `Authorization: Bearer qcb_sk_...`. Clients that send a header value exactly as you type it, such as claude.ai's request headers, need `Bearer` and a space before the key. | | The variable's name starts with `ANTHROPIC_` | Your config reads `${ANTHROPIC_...}` | Claude Code reads `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` and similar credential names as empty in a remote server's headers. Use `QCB_API_KEY`. | | Two `Authorization` headers were sent | The message reads "Send exactly one Authorization header." | Remove the duplicate, for example a header set both in the config and by a bridge or proxy. | | The key expired | **Status** is Expired | Rotate it, or create a new key. The portal offers lifetimes of 30, 60, 90, 180 or 365 days. | | The key was revoked | **Status** is Revoked | A revoked key cannot be restored or rotated. If it was replaced by a rotation, use the new key from that rotation. Otherwise create a new key. | | The key is suspended | **Status** is Suspended | The organization admin who created the key was deactivated or left the organization. If that admin is reactivated, the key works again. Otherwise another organization admin rotates the key, and the new key belongs to that admin. | | Queue CallBack has switched API keys off for the whole service | The **Create API key** button is off and the **API keys** page says "API keys are turned off on this server…" | Nothing to fix on your side. Contact Queue CallBack support. | The server remembers a refusal for about 10 seconds. If the same key starts working again, for example after its creator is reactivated, wait that long and reconnect the client. For up to about 30 seconds, a key that stops working (revoked, expired or suspended) gives tool results with the code `invalid_credentials`. After that, every request gets HTTP 401 `invalid_token`. Keys are described in full in [Rotate, revoke and suspension](/docs/mcp/access#rotate-revoke-and-suspension). ## The client opens a browser to sign in Claude and ChatGPT open a Queue CallBack sign-in page when you connect them. That is expected: sign in with your Queue CallBack portal account ([Sign in from Claude](/docs/mcp/connect#sign-in-from-claude), [Sign in from ChatGPT](/docs/mcp/connect#sign-in-from-chatgpt)). The connection is then read-only. Many other MCP clients also start a browser sign-in when the Queue CallBack MCP server answers 401. Claude Code, VS Code, Cursor, Zed, Gemini CLI and Codex do this. In those clients it means the request reached the server without a usable API key. Queue CallBack supports sign-in from Claude and ChatGPT only, so connect other clients with an API key. If such a sign-in completes anyway, the connection gets at most the read scopes `ivr:read`, `reports:read`, `callbacks:read`, `queues:read` and `org:read`: caller numbers stay masked, no tool that changes something is listed, and the sign-in can stop working without notice. Fix, for any client other than Claude and ChatGPT: 1. Add the header `Authorization: Bearer ${QCB_API_KEY}` to the server entry in your client, in the form your client uses. [Connect a client](/docs/mcp/connect) has a copy-paste entry for each client. 2. Make sure `QCB_API_KEY` is set where the client starts (see [Cannot connect](#cannot-connect-401-invalid_token)). 3. Cancel the browser sign-in, restart the client, and reconnect. In Claude Code, an entry that has an `Authorization` header reports a failed connection on 401 and does not open a browser. So if Claude Code offers to sign in, its entry for the server has no header at all. Check which entry it uses with `claude mcp get queuecallback`. If a sign-in completed, call `get_me`. `actor_type` `oauth` means the client connected by sign-in, not with your API key. ## Sign-in from Claude or ChatGPT fails or repeats When Claude or ChatGPT signs in to the Queue CallBack MCP server, the sign-in can fail, or the client can ask you to sign in again and again. Find the cause in this table. A refused sign-in changes nothing. | What you see | Cause | Fix | |---|---|---| | The sign-in finishes, then the client asks you to sign in again | The account you signed in with is not an active user of a Queue CallBack organization, for example a deactivated account, or an account your browser was already signed in to that is not your portal account. The server answers 401 `invalid_token`, and the client starts a new sign-in | Sign out of the Queue CallBack portal in that browser, reconnect, and sign in with the portal account you use at `https://dashboard.queuecallback.com`. If that account was deactivated, ask an organization admin or Queue CallBack support | | An error with `mcp_disabled` | The organization's API access is off. The sign-in worked, but every request is refused | See [403 mcp_disabled on every request](#403-mcp_disabled-on-every-request) | | An error with `no_organization` | The account you signed in with belongs to no Queue CallBack organization | Ask an organization admin to add you, or sign in with the account of your organization | | An error with `insufficient_scope`, or the client asks you to sign in again to approve more access | The sign-in granted none of the read scopes the server asks for, for example because the client asked for other scopes | Remove the connector and add it again, then approve the access on the Queue CallBack page. In Claude, choose **Use Claude's published identity (Recommended)** under **OAuth client** | | Claude cannot complete the sign-in at all | The connector was added with **Register automatically** or **Use your own OAuth client**. Queue CallBack offers no automatic registration and issues no client IDs | Remove the connector and add it again with **Use Claude's published identity (Recommended)** ([Sign in from Claude](/docs/mcp/connect#sign-in-from-claude)) | | An error with `authorization_server_unavailable` | The server could not check the sign-in for a moment | Wait the `Retry-After` seconds, about 5, and try again. You do not need to sign in again | | Another client, such as Claude Code, Cursor or VS Code, signs in or fails to | Queue CallBack supports sign-in from Claude and ChatGPT only | Connect that client with an API key ([The client opens a browser to sign in](#the-client-opens-a-browser-to-sign-in)) | To see what a working sign-in has, ask the client to call `get_me`: `actor_type` is `oauth`, and `scopes` lists the read scopes in effect ([Check the connection](/docs/mcp/connect#check-the-connection)). ## A change fails after sign-in A sign-in from Claude or ChatGPT is read-only. It never grants a write scope, `ivr:publish`, `callbacks:dial` or `pii:read`, whatever your role in Queue CallBack, and a User's sign-in has no `ivr:read` either. So when you ask a signed-in connection to change something: - The agent says it has no tool for the change. The Queue CallBack MCP server does not list tools that change something, place calls or publish flows for a signed-in connection, and a call to one by name is refused with the tool error `insufficient_scope`, whose `required_scope` names the scope the change needs. - A search by phone number, the `caller` filter or sorting by caller fails with the tool error `insufficient_scope` and `required_scope` `pii:read`. Caller numbers stay masked for every signed-in connection ([Caller numbers are masked](#caller-numbers-are-masked)). - An HTTP 403 `insufficient_scope` before any tool runs means the sign-in granted none of the read scopes. See [Sign-in from Claude or ChatGPT fails or repeats](#sign-in-from-claude-or-chatgpt-fails-or-repeats). Fix: make changes through a connection with an API key that has the scopes for the job. An organization admin creates the key ([Create an API key](/docs/mcp/access#create-an-api-key)). In Claude, use Claude Desktop with the `mcp-remote` bridge, a custom connector with the Request headers beta, or Claude Code ([Claude Desktop](/docs/mcp/connect#claude-desktop)). ChatGPT cannot send an API key; use the Codex CLI or the OpenAI Responses API instead. When to use which: [Sign-in or API key](/docs/mcp/access#sign-in-or-api-key). ## Signed in to the wrong organization A sign-in from Claude or ChatGPT acts in the organization of the Queue CallBack account you signed in with. There is no organization choice, and no tool takes an organization id. Each Queue CallBack account belongs to one organization. 1. Ask the client to call `get_me` and `get_organization`. `organization_id` and the organization's name show where the connection acts. 2. If it is the wrong organization, you signed in with another account, for example one your browser was already signed in to. Remove the connector in the client (in Claude: **Customize** > **Connectors**, **Remove**). 3. Sign out of the Queue CallBack portal in that browser. 4. Add the connector again and sign in with the account of the right organization. To work with several organizations from one client, connect with one API key per organization instead ([Can I use one connection for more than one organization?](#can-i-use-one-connection-for-more-than-one-organization)). ## 403 mcp_disabled on every request The Queue CallBack MCP server answers every request with HTTP 403 and the code `mcp_disabled` while the organization's API access is off. The key itself is fine: ```json { "jsonrpc": "2.0", "id": null, "error": { "code": -32001, "message": "API and MCP access is not enabled for this organization", "data": { "code": "mcp_disabled" } } } ``` Nothing in the key or the client changes this answer. If you see it, contact Queue CallBack support with the `X-Request-Id` ([Get support](#get-support)). If access goes off during a session, tool calls fail with `mcp_disabled` in the tool result for up to about 30 seconds; after that, every request gets HTTP 403 `mcp_disabled`. Once access is back, allow about 10 seconds, then reconnect the client. ## A tool is missing The Queue CallBack MCP server lists only the tools that a connection may use. A tool missing from the list is not broken. One of the rules below hides it, and a call to it by name is refused with the code in the table, before anything is sent. To find the rule, compare the scopes your key shows in the portal (**Settings**, then **Manage API keys**) with the `scopes` that `get_me` returns. In the portal's key list, a scope that does not take effect is struck through. Hold the pointer over it to see why: an organization setting, or the role of the admin who created the key. `get_me` lists only the scopes that take effect. | Missing | Cause | Fix | |---|---|---| | Any tool | The key does not hold every scope the tool needs. Each tool's scopes are in the [tool reference](/docs/mcp/tools). Called by name, the tool answers `insufficient_scope` with `required_scope`. | Scopes cannot be added to an existing key, and rotating keeps the same scopes. An organization admin creates a new key with the scope ([Scopes](/docs/mcp/access#scopes)) and revokes the old one. | | All IVR flow tools (the [IVR flows group](/docs/mcp/tools#ivr-flows-preview) of the tool reference, such as `list_flows` and `get_flow`) | The organization does not have the Custom IVR add-on. `get_me` shows `custom_ivr_enabled: false`. Called by name, they answer `custom_ivr_not_enabled`. The queue, callback and callback report tools still work. | See [IVR tools are gone after a plan change](#ivr-tools-are-gone-after-a-plan-change). | | All IVR flow tools, for a sign-in | The signed-in person is a User. The User role holds no `ivr:read`, so a User's sign-in cannot read IVR flows. Called by name, they answer `insufficient_scope`. | An organization admin signs in, or uses an API key. | | `get_ivr_summary`, `list_ivr_calls`, `get_ivr_call`, `get_flow_decisions`, `list_ivr_flow_stats` | The IVR call reports are for organization admins of organizations with the Custom IVR add-on. `get_me` shows `ivr_reporting_enabled: false`. Called by name, they answer [`ivr_reporting_not_enabled`](/docs/mcp/errors#ivr_reporting_not_enabled). | Use the callback reports, which every role reads, or connect as an organization admin of an organization with the add-on. | | `create_flow_draft`, `edit_flow_draft`, `discard_draft`, `publish_flow`, `restore_flow_version` | `ivr:write` and `ivr:publish` take effect only when the organization edits its IVR flows through drafts and publishing. Called by name, these tools answer `insufficient_scope` for `ivr:write` or `ivr:publish`, even when the key holds them. | Ask Queue CallBack support. | | `add_callback` | The tool is listed only when `pii:read` takes effect. That needs `pii:read` on the key, and caller-data unmasking turned on for the organization. A healthcare-locked organization never unmasks. `get_me` shows `pii_allowed: false`. Called by name, the tool answers `insufficient_scope` for `pii:read`. | Ask Queue CallBack support to turn on caller-data unmasking, then create a key with `callbacks:write` and `pii:read`. See [add_callback](/docs/mcp/tools#add_callback). | | Every tool that changes something | Queue CallBack can switch changes off on the server. While changes are off, clients see only the read-only tools. A call to one, for example from an older tool list, answers `writes_disabled`. | Make the change in the portal, or try again later. | | `update_queue_settings`, or `set_queue_voice` and `set_queue_language` | Queue CallBack can switch queue callback settings changes, and queue voice and language changes, off on their own. A call while one is off answers `queue_settings_disabled` or `queue_writes_disabled`. | Change the settings, voice or language in the portal, under **Configurations**, or try again later. | After a change to a key, its scopes, your organization or a server switch, the tool list can take up to about 90 seconds to update. The server reuses a key's description for up to 30 seconds, and clients may cache the list for up to 60 seconds. Many clients read the list only when they connect, so reconnect the client to refresh the list (in Claude Code, run `/mcp` and reconnect the server) or restart it. Your client can also hide tools. Some clients load tool details only when needed, and some let you switch tools off, for example a tool picker. Check the client's own tool list before you change the key. ## 415, 400 or 405 from your own HTTP requests The Queue CallBack MCP server accepts JSON-RPC requests sent with `POST` to `https://mcp.queuecallback.com/mcp`. Hand-written requests usually fail on the headers. 415, 400 and 405 come as plain text, not JSON-RPC. A 404 comes from the web server in front as an HTML page. | Status | Cause | Fix | |---|---|---| | 415 | `Content-Type` is missing or is not `application/json` | Send `Content-Type: application/json`. | | 400 | `Accept` does not list both `application/json` and `text/event-stream` | Send `Accept: application/json, text/event-stream`. The server still answers with one JSON response. | | 405 | The request used `GET` or `DELETE` | Use `POST`. | | 404 | The path is not `/mcp` | Use the exact URL `https://mcp.queuecallback.com/mcp`. | The server checks the API key before the headers. A request without a valid key gets 401 first, also for `GET`. So 415, 400 and 405 appear only once the key is accepted. A request from a web page on another site is refused with 403 `cross_origin_refused`: call the server from a program, not from browser code. The server is stateless: each `POST` gets one JSON answer, and there is no session id to keep. Requests are limited to 1 MiB. The key test in [Start here](#start-here-three-checks) is a complete working request. For an MCP SDK in place of raw HTTP, see [Connect a client](/docs/mcp/connect). ## 429: too many requests The Queue CallBack MCP server answers HTTP 429, or a tool result with a 429 code, when a connection sends more than its share. Wait the number of seconds in the `Retry-After` header or in `retry_after_seconds`, then retry. | Code | Means | |---|---| | `concurrency_limited` | Too many requests at once, from one API key or from the whole organization | | `rate_limited` | Too many requests a minute, from one API key or from the whole organization | | `queue_write_limited` | Too many queue callback settings changes, or voice and language changes, in a short time for the organization (each kind has its own limit) | Some tools, such as `add_callback` and `set_organization_name`, have limits of their own. The values are in [Limits](/docs/mcp/errors#limits). A per-address limit also applies at the web server in front. Its 429 is a JSON-RPC error with the code `rate_limited`, the message "Too many requests from this address. Retry in a second." and `Retry-After: 1`, and it carries no `X-Request-Id`. To stay under the limits: 1. Ask the agent to run calls one after another instead of many at once. 2. Use filters, shorter date ranges and summary tools such as `get_callback_summary` instead of paging through long lists. 3. Remember that every key in one organization shares the organization's limits. 4. Before you retry a change, read the current state, so a change that already went through is not made twice. See [Retries](/docs/mcp/errors#retries). ## confirm_refused when making a change On the Queue CallBack MCP server, most changes that reach callers need the user's agreement and a confirm token. `add_callback` is the exception: it asks for approval on every call but takes no confirm token, and its idempotency key stops a retry from adding a second callback. `publish_flow` needs the token that `validate_flow` returned. `requeue_callback`, `restore_flow_version`, `update_queue_settings`, `set_queue_voice` and `set_queue_language` work in two calls: the first changes nothing and reads nothing, and returns the arguments it will apply (`will_apply`) and a `confirm_token`; the second repeats the same arguments and adds the token. A token is single use, lasts 10 minutes, and is bound to the tool, the key, the organization and the argument values. The full flow, including how to show the user what will change, is in [Confirm tokens](/docs/mcp/safety#confirm-tokens). A refused token changes nothing. The message says why and how to get a new one, for example: ```text The confirm token was refused: the confirm token has expired. Nothing was changed; call update_queue_settings again without confirm_token for a new token, then call it again with that token. ``` A token is used up as soon as the server accepts it. So when the second call itself fails (a timeout, a 429, a refusal), its error carries `confirm_token_spent: true` and a `next_step` that says how to retry: a new first call (for `publish_flow`, `validate_flow` again) and, for `requeue_callback`, the same `idempotency_key`. | Reason in the message | Cause | Fix | |---|---|---| | "the confirm token has expired" | More than 10 minutes passed, often while waiting for the user | Repeat the first call (or `validate_flow`) and use the new token. | | "it was already used, by an earlier call that may have made this change" (with `confirm_token_spent: true`) | The second call ran before, perhaps in a retry | The change may have been made. Read the current state first (for example `get_queue`, `list_flow_versions` or `get_requeue_status`). Only if nothing changed, repeat the first call for a new token; for `requeue_callback`, send the same `idempotency_key` as the earlier call. | | "the confirm token was issued for another action, caller or set of values" | An argument changed between the two calls, or the token came from another key or another tool | Repeat the first call with the exact arguments you will send, then send them unchanged with the token. | | "the confirm token is not a valid token from this server" | The token was cut off, edited or invented | Use the token exactly as returned. Never make one up. | | "too many confirm tokens are outstanding; try again shortly" | A short-lived limit on the server | Wait a moment and repeat the first call. | `confirm_required` means `publish_flow` was called without the token from `validate_flow`. Call `validate_flow` on the draft, show the user the result and the `diff_flow` changes, then publish with that token. If the draft changed after validating, validate again. ## Claude Code saves a result to a file Claude Code keeps a large tool result out of the conversation and saves it to a file. By default it does this above 50,000 characters, unless the tool declares a higher limit in `anthropic/maxResultSizeChars` (up to 500,000). Every tool of the Queue CallBack MCP server declares a limit that matches the server's own result limit for that tool. So a current Claude Code keeps Queue CallBack results in the conversation. If you see it anyway: 1. Claude can still read the saved file. Ask it to. 2. Update Claude Code. 3. Ask for less: a shorter date range, a filter, a smaller `limit`, or for `get_flow` the `outline` option or a single `node_id`. The server has its own result limit as well. Above it, long lists come back shortened and marked `truncated: true`, and other results fail with `result_too_large`. Narrow the request in the same way. See [Limits](/docs/mcp/errors#limits). ## Caller numbers are masked The Queue CallBack MCP server masks caller data by default. A caller number keeps only its last four digits, for example `+*******4567`. Digits that callers keyed in are hidden. This is expected and is not an error. A connection sees unmasked caller data only when all three hold. A sign-in from Claude or ChatGPT never does, because sign-in never grants `pii:read`. 1. The API key holds `pii:read`. 2. Caller-data unmasking is turned on for the organization. Queue CallBack support controls this setting: to turn it on, an organization admin emails support@queuecallback.com with the organization's name. 3. The organization is not healthcare-locked. A healthcare-locked organization stays masked for every key. `get_me` shows the result as `pii_allowed`. Without unmasking, a search made only of digits and phone punctuation is refused with `insufficient_scope`. Other searches leave out the number columns. The `caller` filter and sorting by caller are refused. `add_callback` is not listed. More in [Caller data](/docs/mcp/safety#caller-data). ## IVR tools are gone after a plan change The Queue CallBack MCP server lists the IVR flow tools only while the organization has the Custom IVR add-on, the IVR flow builder. Where the portal's **Billing** page offers it, it is called the Custom IVA plan. When the add-on ends, for example after a plan change, the IVR flow tools disappear from every key's tool list. `get_me` shows `custom_ivr_enabled: false`. An IVR tool called from the old tool list, or by name, fails with `custom_ivr_not_enabled`. The queue, callback and callback report tools keep working. The IVR call reports can stay open to organization admins for a time after the add-on ends; `ivr_reporting_enabled` in `get_me` says whether they are. Your keys do not need replacing. Existing keys keep their IVR scopes, which stop taking effect while the add-on is off. They work again when it returns. While the add-on is off, new keys cannot be given IVR scopes. Fix: 1. If the **Billing** page offers the plan, an organization admin can restore it there. Otherwise ask Queue CallBack support. 2. Reconnect the client. The tool list can take up to about 90 seconds to update. If reading works but edits are refused with `custom_ivr_queue_required`, the flow's queue is not a Custom IVR queue. See [Tool errors](/docs/mcp/errors#tool-errors). How the IVR tools work is in [IVR flows](/docs/mcp/ivr). ## Callbacks are not dialing When callers ask for callbacks but the callbacks are not dialed, check the organization's RingCentral connection, then the queue. An agent reads both through the Queue CallBack MCP server with `queues:read`; neither check changes anything. 1. Call `list_queues`, or `get_queue` with the queue's id, and read `ringcentral_connection`. It is the organization's RingCentral connection, the same for all of its queues: | `ringcentral_connection` | Meaning | Fix | |---|---|---| | `connected` | The connection is current. | Go to step 2. | | `needs_reconnect` | The connection has expired and was not renewed, so callbacks may fail to dial until an organization admin reconnects RingCentral in the portal. | An organization admin opens **RingCentral Connection** in the portal and connects RingCentral again. | | `not_connected` | The organization has no RingCentral connection, so callbacks cannot be dialed until an organization admin connects RingCentral in the portal. | An organization admin opens **RingCentral Connection** in the portal and chooses **Connect RingCentral**. | | not in the answer | The server cannot tell. | Check the **RingCentral Connection** page in the portal. | 2. Read the queue itself: `status` is `active` while the queue runs, and the queue's line must be registered to place callbacks (`registration_status` `registered` or `active` in `list_queues`; `last_registration` and `registration_error` in `get_queue`). An organization admin starts a stopped queue in the portal under **Configurations**. If the line stays `not_registered`, contact Queue CallBack support with the queue's name ([Get support](#get-support)). 3. To see what happened to one callback, call `get_callback_journey` with its id (`reports:read`), or `list_callback_queue` for the open ones (`callbacks:read`; [Recipes](/docs/mcp/recipes#waiting-callbacks-right-now)). No tool reconnects RingCentral, starts a queue or creates one: those are portal tasks. ## FAQ ### Do I need the Custom IVR add-on? No. Without the Custom IVR add-on, an organization uses the Queue CallBack MCP server for its queues, its callbacks and the callback reports. The add-on adds the IVR flow tools and the IVR call reports, which are for organization admins. ### Does Queue CallBack see my prompts? No. The Queue CallBack MCP server receives only the tool calls your AI client sends: the tool's name and its arguments, plus the messages a client sends to connect and list tools. Your prompts, the conversation and the model's replies stay with your client and its model provider. Tool results go back to your client, and from there to the model provider your client uses, under that provider's terms. The Queue CallBack MCP server logs each tool call with the argument names, not their values (the error text of a failed call, up to 300 characters, can quote a value that failed a check). The Queue CallBack API still acts on the argument values: it runs the search or stores the new callback. The full list is in [What Queue CallBack records](/docs/mcp/safety#what-queue-callback-records). ### Does the Queue CallBack MCP server use an AI model? No. The Queue CallBack MCP server runs no AI model. For each tool call it checks the API key and the arguments, sends the request to the Queue CallBack API, and returns the answer. The model belongs to your AI client. If your organization has Queue CallBack's in-portal assistant, that is a separate feature and plays no part when you connect your own client. ### Can I use one connection for more than one organization? No. An API key acts in exactly one organization, the one it was created in, and a sign-in from Claude or ChatGPT acts in the signed-in person's own organization. No tool takes an organization id. For several organizations, an organization admin of each creates a key there. Then add the server once per organization, each entry with its own name and its own variable. In Claude Code's `.mcp.json`: ```json { "mcpServers": { "queuecallback-east": { "type": "http", "url": "https://mcp.queuecallback.com/mcp", "headers": { "Authorization": "Bearer ${QCB_EAST_API_KEY}" } }, "queuecallback-west": { "type": "http", "url": "https://mcp.queuecallback.com/mcp", "headers": { "Authorization": "Bearer ${QCB_WEST_API_KEY}" } } } } ``` Name the organization in your prompt, or ask the agent to call `get_me` on each server first. ### Is there a REST API? No documented one. The Queue CallBack MCP server is the interface for programs, and these pages document only the MCP server. MCP is JSON-RPC over HTTPS, so any language with an MCP SDK, or an HTTP client, can call it. [Connect a client](/docs/mcp/connect) has SDK and model-API examples. ### Can an agent place phone calls? Only two tools of the Queue CallBack MCP server place real phone calls. Claude Code asks for your approval on every call of both, even when an allow rule matches. Other clients, Claude Desktop through `mcp-remote` included, may not, so the agent also asks in the conversation ([Approval prompts](/docs/mcp/safety#approval-prompts)). | Tool | What it does | Needs | |---|---|---| | `requeue_callback` | Puts an expired, failed or cancelled callback back in the queue. The system then calls an agent and the customer. Two calls with a confirm token. At most 5 requeues per callback in 24 hours by default. | `callbacks:dial` and `callbacks:read` | | `add_callback` | Adds a callback for a number to a running queue. Within about 30 seconds the system rings the queue and, once an agent answers, calls the number. Refused if that number already has a callback waiting in that queue. At most 30 an hour. | `callbacks:write` and `pii:read`, with caller-data unmasking on for the organization | `update_queue_settings` places no call itself, but turning on `auto_requeue` makes the queue dial expired callbacks again at their next expiry, up to `max_requeue_attempts` times. It needs `queues:write` and asks for approval on every call. No other tool places, transfers or ends a call. `complete_callback` marks a callback done without calling anyone. A sign-in from Claude or ChatGPT cannot place calls: it never grants `callbacks:dial`, `callbacks:write` or `queues:write`. A key without `callbacks:dial`, `callbacks:write` and `queues:write` cannot place calls or change how the queue redials. The **Read only** shortcut in the **Create API key** dialog selects the read scopes that take effect in your organization, without `pii:read`. See [requeue_callback](/docs/mcp/tools#requeue_callback) and [add_callback](/docs/mcp/tools#add_callback). ## Get support Email Queue CallBack support at support@queuecallback.com. We respond to email during US business hours. Report a security problem to security@queuecallback.com instead ([Report a security problem](/docs/mcp/safety#report-a-security-problem)). ### What to include - Your organization's name, and your email address in Queue CallBack. - When it happened, with your time zone. - The AI client and its version, and how it connects (an API key in a header, or a bridge such as `mcp-remote`). - The tool name, if a tool call failed, and what you asked the agent to do. - The error code (`error.data.code` or `structuredContent.error.code`) and the message. - The `X-Request-Id` response header, if your client or the key test in [Start here](#start-here-three-checks) shows it. - The `get_me` result, if the client connects. It contains no secret. - The key's name as the portal shows it under **Manage API keys**. Never send the API key itself. Support never needs it. ### If an API key may have leaked Stop the key at once in **Settings**, then **Manage API keys**. Choose **Rotate** to get a new key with the same name and scopes, or **Revoke** if the client is no longer needed. Either stops the leaked key immediately. Open sessions may get `invalid_credentials` for up to about 30 seconds, then HTTP 401. Put the new key in `QCB_API_KEY` and update every client that stored the old key in plain text (Zed, Cline, Junie, `mcp-remote` configs, Claude Code entries added with double quotes, claude.ai connectors: remove and add again). A key pasted into an AI chat has reached that model provider: treat it as leaked even after you delete the message. If you think someone used it, email security@queuecallback.com with your organization's name and the key's name as the portal shows it ([Report a security problem](/docs/mcp/safety#report-a-security-problem)). Never send the key. See [Rotate, revoke and suspension](/docs/mcp/access#rotate-revoke-and-suspension).