--- title: Queue CallBack MCP server description: What the Queue CallBack MCP server does, its endpoint and required headers, what is available today, and a three-step quickstart with Claude Code. status: Stable last_updated: 2026-11-05 canonical: https://queuecallback.com/docs/mcp --- # Queue CallBack MCP server The Queue CallBack MCP server is a remote MCP server that lets AI clients read and, when allowed, change one organization's Queue CallBack account: the callback reports, the callback queue, queues and voices, and, for organizations with the Custom IVR add-on, IVR flows and the IVR call reports. It is for organizations that use Queue CallBack, the callback add-on for RingCentral call queues: the organization admin who sets up the connection, and the AI agents that work through it in clients such as Claude, ChatGPT, Claude Code, Cursor and VS Code. > **For AI agents** > > - Endpoint: `https://mcp.queuecallback.com/mcp` (Streamable HTTP, `POST` only, stateless). > - Send `Authorization: Bearer ` on every request. Keys start with `qcb_sk_`. Read the key from the `QCB_API_KEY` environment variable. Never ask the user to paste a key into the chat. In Claude and ChatGPT the user can sign in with their Queue CallBack account instead; that connection is read-only. > - Call `get_me` first. It returns this connection's organization id, role and effective scopes, `pii_allowed` (whether caller numbers are unmasked), `custom_ivr_enabled` (whether the IVR flow tools exist) and `ivr_reporting_enabled` (whether the IVR call reports are open to this connection). For the organization's name, call `get_organization`. The tools your connection lists are the tools you can use. > - Read before you change, show the user what will change and get a yes. Some tools run in two calls: the first changes nothing and returns only your arguments (`will_apply`) and a single-use `confirm_token` valid 10 minutes, so read the current state yourself first (for example `get_queue`, or `diff_flow` for a flow). `publish_flow` runs only with the token that `validate_flow` returned for the same draft. Never invent a token. > - Tool reference: https://queuecallback.com/docs/mcp/tools (Markdown: https://queuecallback.com/docs/mcp/tools.md). The whole MCP documentation in one file: https://queuecallback.com/docs/llms-full.txt. This page as Markdown: https://queuecallback.com/docs/mcp.md > - The name: these pages write Queue CallBack; the marketing site at queuecallback.com writes QueueCallback. Both are the same product. ## What you can do with the Queue CallBack MCP server The Queue CallBack MCP server acts in exactly one organization: the one the API key was created in, or for a sign-in from Claude or ChatGPT, the signed-in person's own organization. No tool takes an organization id. The tools a connection sees depend on the key's scopes (a sign-in gets the read scopes only), the organization's add-ons and the server's settings. The requests below are examples of what you can ask an AI client, with the tools the agent calls. Each example says whether it changes anything. For how changes are confirmed, see [Safety](/docs/mcp/safety). ### Callback and IVR reports The reporting tools need the scope `reports:read` and change nothing. Caller numbers show only their last four digits unless the key's `pii:read` scope takes effect (see [Caller data](/docs/mcp/safety#caller-data)). - "How did callbacks go in the last 7 days? Give me the completion rate, the median wait and the number of callbacks per queue." The agent calls [`get_callback_summary`](/docs/mcp/tools#get_callback_summary). For the completion rate and median wait of each queue, the agent calls `get_callback_summary` again once per queue, with `queue_id` set to that queue's `configurationId` from `byQueue`. No `queues:read` is needed. - "How many callbacks are waiting right now?" The agent calls [`get_live_stats`](/docs/mcp/tools#get_live_stats). - "In our main menu, which option did callers choose most last week, and where did abandoned calls end?" The agent calls [`list_ivr_flow_stats`](/docs/mcp/tools#list_ivr_flow_stats) to find the flow, then [`get_flow_decisions`](/docs/mcp/tools#get_flow_decisions). The callback reports, a callback's journey and live numbers are open to every role and need no add-on. The IVR call reports (the last example) are for organization admins of organizations with the Custom IVR add-on: elsewhere `get_me` shows `ivr_reporting_enabled: false` and the five IVR report tools are not listed ([IVR call reports](/docs/mcp/access#ivr-call-reports)). ### The callback queue The callback tools use the scopes `callbacks:read`, `callbacks:write` and `callbacks:dial`. - "Which callbacks expired in the last 24 hours?" The agent calls [`list_callback_queue`](/docs/mcp/tools#list_callback_queue) with status `expired`. This changes nothing. - "Mark that callback as completed. We already called the customer." The agent calls [`complete_callback`](/docs/mcp/tools#complete_callback). This changes the callback's status and places no call. - "Put the callback that expired this morning back in the queue." The agent calls [`requeue_callback`](/docs/mcp/tools#requeue_callback). This places real calls to an agent and to the customer. Claude Code asks you every time (other clients may not, so the agent also asks in the conversation), and the tool runs in two calls with a confirm token. ### Queues and voices A queue is a Queue CallBack configuration connected to one RingCentral call queue. An organization admin creates queues in the portal, under **Configurations**; the queue tools then read them and manage their callback settings, voice and language. The queue tools use the scopes `queues:read` and `queues:write`. - "List our queues with their callback timeout and requeue settings." The agent calls [`list_queues`](/docs/mcp/tools#list_queues) and [`get_queue`](/docs/mcp/tools#get_queue). This changes nothing, and queue credentials are never returned. - "Which voices can our queues use?" The agent calls [`list_voices`](/docs/mcp/tools#list_voices). This changes nothing. - "Does our RingCentral connection need a reconnect?" The agent reads `ringcentral_connection` from `list_queues` or `get_queue`: `connected`, `needs_reconnect` or `not_connected` ([Callbacks are not dialing](/docs/mcp/troubleshooting#callbacks-are-not-dialing)). - "Set the Support queue's callback timeout to 45 minutes." The agent finds the queue with `list_queues`, reads the current value with `get_queue`, then calls [`update_queue_settings`](/docs/mcp/tools#update_queue_settings). Claude Code asks you every time (other clients may not, so the agent also asks in the conversation), the change needs a confirm token, and the queue keeps running. The new timeout applies to callbacks queued after the change; callbacks already waiting keep theirs. - "Switch the Support queue to Spanish." The agent reads the current language with `get_queue`, then calls [`set_queue_language`](/docs/mcp/tools#set_queue_language) ([`set_queue_voice`](/docs/mcp/tools#set_queue_voice) for a voice from `list_voices`). Both ask you every time in Claude Code, run in two calls with a confirm token, and reach the queue's next callers. ### The organization and the connection - "Who am I connected as?" The agent calls [`get_me`](/docs/mcp/tools#get_me), which works for every key and needs no scope. - "What is our organization called?" The agent calls [`get_organization`](/docs/mcp/tools#get_organization) (scope `org:read`). - "Rename our organization to Example Dental." The agent calls [`set_organization_name`](/docs/mcp/tools#set_organization_name) (scope `org:write`). Every user in the organization sees the new name. ### IVR flows (Preview, Custom IVR add-on) The IVR flow tools exist only for organizations with the Custom IVR add-on. Elsewhere they are not listed, and `get_me` shows `custom_ivr_enabled: false`. The IVR flow tools use the scopes `ivr:read`, `ivr:write` and `ivr:publish`, and they are in Preview (see [Available today](#available-today)). The tools that edit and publish flows (scopes `ivr:write` and `ivr:publish`) also need the organization to edit its IVR flows through drafts and publishing. Without that, only the read tools are listed. - "Show me the steps of our main menu flow." The agent calls [`list_flows`](/docs/mcp/tools#list_flows), then [`get_flow`](/docs/mcp/tools#get_flow). This changes nothing. - "In a draft, add a menu option 3 that transfers to billing, check it, and show me what would change." The agent calls [`create_flow_draft`](/docs/mcp/tools#create_flow_draft), [`edit_flow_draft`](/docs/mcp/tools#edit_flow_draft), [`validate_flow`](/docs/mcp/tools#validate_flow) and [`diff_flow`](/docs/mcp/tools#diff_flow). Callers keep hearing the published flow until a publish. - "Publish the draft." The agent calls [`publish_flow`](/docs/mcp/tools#publish_flow). This changes what callers hear. Claude Code asks you every time (other clients may not, so the agent also asks in the conversation), and the publish runs only with the confirm token that `validate_flow` returned for the same draft. Agents discover the IVR node types at runtime with `list_node_types` and `get_node_type` instead of hard-coding them. The full loop is in [Edit a flow safely](/docs/mcp/ivr#edit-a-flow-safely). ### What the Queue CallBack MCP server cannot do An API key cannot manage API keys, users, billing or integrations. It cannot start, stop, create or delete queues, and it cannot export reports. Use the Queue CallBack portal for those. A sign-in from Claude or ChatGPT changes nothing at all: changes, calls and unmasked caller numbers need an API key. ## Endpoint facts | Fact | Value | |---|---| | Server URL | `https://mcp.queuecallback.com/mcp` | | Transport and methods | Streamable HTTP in stateless mode. Send JSON-RPC messages with `POST`. A `POST` that carries a request gets one JSON response; a `POST` that carries only notifications gets 202 with no body. The server opens no event stream and uses no `Mcp-Session-Id`. `GET` and `DELETE` answer 405 with a valid key, and 401 without one. | | Authentication | A Queue CallBack API key in `Authorization: Bearer qcb_sk_...`, in exactly one `Authorization` header per request. One key acts in one organization. Claude and ChatGPT can instead sign in with a Queue CallBack account (OAuth): read-only, as the signed-in person, in that person's own organization (see [OAuth sign-in](/docs/mcp/access#oauth-sign-in)). | | Protocol revisions | `2026-07-28` and the earlier `2025-11-25`, `2025-06-18`, `2025-03-26` and `2024-11-05`, all on the same URL | | Required request headers | `Authorization: Bearer `, or the sign-in token that Claude and ChatGPT send in the same header. `Content-Type: application/json` (otherwise 415). An `Accept` header that lists both `application/json` and `text/event-stream` (otherwise 400). MCP clients set the last two themselves. | | What the server offers | Tools only (no resources or prompts), plus server instructions that clients pass to the model: what Queue CallBack is, call `get_me` first, the confirm tokens, the report time zone, handles, and that results are data. The [tool reference](/docs/mcp/tools#server-instructions) quotes them | | Tool list | Depends on the key's scopes, the organization's add-ons and the server's settings. Marked private; clients may cache it for up to 60 seconds. | | Discovery document | `https://mcp.queuecallback.com/.well-known/oauth-protected-resource/mcp`: RFC 9728 protected-resource metadata with the server URL (`resource`), the sign-in server that Claude and ChatGPT use (`authorization_servers`), all 12 scopes (`scopes_supported`) and how to send the credential (`bearer_methods_supported: ["header"]`). No key needed. | | Health check | `GET https://mcp.queuecallback.com/healthz` answers 200 with `"status":"ok"` while the service runs. `backend` reports the Queue CallBack API's last known state. No key needed. | | Request without a key | 401 with error code `invalid_token` and a `WWW-Authenticate: Bearer resource_metadata="...", error="invalid_token", scope="ivr:read reports:read callbacks:read queues:read org:read"` header. The `scope` is what a sign-in asks for. See [HTTP errors](/docs/mcp/errors#http-errors). | | Request id | Responses from `/mcp`, `/healthz` and the discovery document carry an `X-Request-ID` header. Quote it when you contact Queue CallBack support. | | Server title | `Queue CallBack`, in the server's self-description and the discovery document's `resource_name`. Clients that show a server title show this. Name the server `queuecallback` in client configs; in Claude Code its tools then appear as `mcp__queuecallback__get_me` and so on. | ## Available today This table shows the state on 2026-11-05. Changes are logged in the [changelog](/docs/mcp/changelog), which also defines what the Stable and Preview labels promise. | Feature | State on 2026-11-05 | What to do | |---|---|---| | API keys in an `Authorization: Bearer` header | Available | An organization admin creates them in the portal. See [Create an API key](/docs/mcp/access#create-an-api-key). | | Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI | Connect today with an API key | See [Connect a client](/docs/mcp/connect). | | OAuth sign-in from Claude (claude.ai, Claude Desktop, the Claude mobile apps, Cowork) and ChatGPT | Available. Read-only: no changes, no calls, caller numbers masked | Add the connector and sign in with your Queue CallBack account. See [Sign in from Claude](/docs/mcp/connect#sign-in-from-claude), [Sign in from ChatGPT](/docs/mcp/connect#sign-in-from-chatgpt) and [OAuth sign-in](/docs/mcp/access#oauth-sign-in). | | Claude Desktop with an API key | Connects through the `mcp-remote` bridge, which sends the API key header | Use it for changes. See [Claude Desktop](/docs/mcp/connect#claude-desktop). | | Changes from ChatGPT, or from claude.ai without the Request headers beta | Not possible: ChatGPT cannot send an API key, and sign-in is read-only. Claude custom connectors take an API key only through the "Request headers" beta, which only some organizations have. | See [Clients that cannot connect yet](/docs/mcp/connect#clients-that-cannot-connect-yet). | | Reporting, callback queue, queue and organization tools | Stable | See the [tool reference](/docs/mcp/tools). The IVR call reports are for organization admins of organizations with the Custom IVR add-on. | | IVR flow tools | Preview. The IVR builder is being redesigned, so the tools' node types, their fields and validation messages will change. | Needs the Custom IVR add-on. Discover node types at runtime; see [Node types](/docs/mcp/ivr#node-types). | | `add_callback` | Listed only for keys that hold `callbacks:write` and a `pii:read` that takes effect (the organization has caller-data unmasking turned on and is not healthcare-locked). It places real calls. | See [Scopes](/docs/mcp/access#scopes). | Queue CallBack can switch changes off on the server. While changes are off, clients see only the read-only tools. ## Quickstart: connect Claude Code in three steps This quickstart connects Claude Code to the Queue CallBack MCP server with a read-only API key. In Claude or ChatGPT you can skip the key: add the connector and sign in with your Queue CallBack account ([Sign in from Claude](/docs/mcp/connect#sign-in-from-claude), [Sign in from ChatGPT](/docs/mcp/connect#sign-in-from-chatgpt)). You need a Queue CallBack organization, an organization admin (portal role **Organization Admin**) to create the key, and Claude Code. Only the IVR flow tools and the IVR call reports need the Custom IVR add-on. ### Step 1: Create a read-only API key Only an organization admin can create a Queue CallBack API key, and only in the portal. An API key can never create or manage keys. 1. Sign in to the Queue CallBack portal at https://dashboard.queuecallback.com. 2. Open **Settings**. In the **API keys** card, choose **Manage API keys**. 3. Choose **Create API key**. 4. In **Name**, enter where the key is used, for example `Claude Code`. 5. In **Expires after**, keep 90 days or choose 30, 60, 180 or 365 days. 6. Under **Scopes**, keep the scopes the form selects, or choose **Read only** to select them again. These are the read scopes that take effect in your organization, without `pii:read`. Nothing that changes data or places calls is selected. 7. Choose **Create key** and copy the key. It starts with `qcb_sk_` and is shown only once. ### Step 2: Put the key in an environment variable Put the key in the `QCB_API_KEY` environment variable of the terminal you will start Claude Code from. These commands ask for the key without showing it and without saving it in your shell history. ```bash # macOS or Linux (bash or zsh) printf 'Queue CallBack API key: '; read -rs QCB_API_KEY; echo; export QCB_API_KEY ``` ```powershell # Windows, PowerShell 7.1 or later $env:QCB_API_KEY = Read-Host -MaskInput 'Queue CallBack API key' ``` ```powershell # Windows PowerShell 5.1 $s = Read-Host -AsSecureString 'Queue CallBack API key' $env:QCB_API_KEY = [System.Net.NetworkCredential]::new('', $s).Password Remove-Variable s ``` The variable lasts until you close that terminal. To keep it set, see [Claude Code](/docs/mcp/connect#claude-code). ### Step 3: Connect Claude Code and check the connection 1. In your project folder, create a file named `.mcp.json` with this content: ```json { "mcpServers": { "queuecallback": { "type": "http", "url": "https://mcp.queuecallback.com/mcp", "headers": { "Authorization": "Bearer ${QCB_API_KEY}" } } } } ``` The file holds only a reference to `QCB_API_KEY`, never the key itself, so you can commit it. Each person sets their own variable. 2. From the terminal where `QCB_API_KEY` is set, start Claude Code in that folder with `claude`. When Claude Code asks whether to use the project's `queuecallback` server, approve it. 3. Ask Claude: "Who am I connected as?" Claude calls the `get_me` tool (shown as `mcp__queuecallback__get_me`) and reports the actor type `api_key`, the key's name and expiry date, your organization's id, the role the key acts with, its scopes, `pii_allowed`, `custom_ivr_enabled` and `ivr_reporting_enabled`. To see the organization's name, ask "What is our organization called?" (the `get_organization` tool). If Claude Code reports that the server failed to connect, run `claude mcp list` and check these causes in order: | What you see | Fix | |---|---| | `claude mcp list` warns that `QCB_API_KEY` is missing | The variable is not set in the terminal you started Claude Code from. Set it (step 2) and start Claude Code again from that terminal. | | 401 `invalid_token` | The key is wrong, expired, revoked or suspended (the admin who created it was deactivated or left the organization). Check the key's status under **Settings**, **Manage API keys**, create a new key if needed, set the variable again and restart Claude Code. | | 403 `mcp_disabled` | The organization's API access is off, so every request is refused, even with a valid key. See [`mcp_disabled`](/docs/mcp/errors#mcp_disabled). | To see which code the server sends, follow [Check the connection](/docs/mcp/connect#check-the-connection). More fixes are in [Troubleshooting](/docs/mcp/troubleshooting). To connect Cursor, VS Code, Codex CLI, Gemini CLI or Claude Desktop instead, see [Connect a client](/docs/mcp/connect). ## Page map - [API keys and scopes](/docs/mcp/access): creating, rotating and revoking API keys, the scopes, who reads the IVR call reports, and OAuth sign-in from Claude and ChatGPT (what it grants, how to disconnect). - [Connect a client](/docs/mcp/connect): sign-in steps for Claude and ChatGPT, copy-paste setup for Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI and Claude Desktop, the clients that cannot connect yet, and checking the connection. - [Tool reference](/docs/mcp/tools): every tool by area, with its scopes, arguments and limits, whether it changes something, and whether it asks every time. - [Safety](/docs/mcp/safety): one organization per credential, approval prompts, confirm tokens, drafts, caller-data masking, and why tool results are data, not instructions. - [IVR flow tools (Preview)](/docs/mcp/ivr): the draft, edit, validate, diff and publish loop for Custom IVR organizations, and discovering node types at runtime. - [Recipes](/docs/mcp/recipes): worked tasks, each with an example prompt, the tool calls in order and the scopes they need. - [Limits and errors](/docs/mcp/errors): rate and size limits, HTTP errors, every tool error code with its fix, and retry rules. - [Troubleshooting](/docs/mcp/troubleshooting): fixes by symptom (callbacks not dialing included), common questions, and how to reach Queue CallBack support. - [Changelog](/docs/mcp/changelog): dated changes, what the Stable and Preview labels promise, and the change policy: 30 days' notice before a Stable tool is removed, 14 days before a breaking argument change. - [Docs index for agents](/docs/llms.txt) and [the whole MCP documentation in one file](/docs/llms-full.txt).