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

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:

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:

   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:

   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:

   $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.
   403	mcp_disabled	The organization's API access is off. See 403 mcp_disabled.
   429	concurrency_limited or rate_limited	Too many requests. See 429.
   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). The fields that matter here, with placeholder values:

   {
     "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. For every cause below except two Authorization headers, the answer is:

{
  "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 <key>, 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:

   printf '%s (%s characters)\n' "${QCB_API_KEY:0:7}" "${#QCB_API_KEY}"
   

   $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. If it answers 200, the key is fine and the client is not sending it.

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.

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, 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 has a copy-paste entry for each client.
2. Make sure QCB_API_KEY is set where the client starts (see Cannot connect).
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.

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

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

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). In Claude, use Claude Desktop with the mcp-remote bridge, a custom connector with the Request headers beta, or Claude Code (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.

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?).

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:

{
  "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). 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.

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.

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 is a complete working request. For an MCP SDK in place of raw HTTP, see Connect a client.

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.

Some tools, such as add_callback and set_organization_name, have limits of their own. The values are in 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.

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.

A refused token changes nothing. The message says why and how to get a new one, for example:

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.

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.

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.

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. How the IVR tools work is in IVR flows.

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

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

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.

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:

{
  "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 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).

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 and 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).

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 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). Never send the key. See Rotate, revoke and suspension.