Access, API keys and scopes

Claude and ChatGPT connect to the Queue CallBack MCP server by signing in with a Queue CallBack account, read-only. Every other client, and every task that changes something, uses an API key that an organization admin creates in the portal under Settings, API keys. Each API key works in one organization only, with the scopes chosen for it, and never with more rights than the admin who created it.

For AI agents: this page is also available as Markdown at https://queuecallback.com/docs/mcp/access.md. The whole MCP documentation in one file: https://queuecallback.com/docs/llms-full.txt

The Queue CallBack MCP server does not need the Custom IVR add-on. Without it, an organization uses the server for its queues, its callbacks and the callback reports. The add-on adds the IVR flow tools and the IVR call reports.

Roles

Only an organization admin can manage Queue CallBack API keys.

An API key can never list, create, rotate or revoke keys.

A key follows the current role of the admin who created it. If that admin becomes a User, the key narrows to the scopes a User may hold (reports:read, pii:read, callbacks:read, callbacks:write, callbacks:dial, queues:read and org:read) and can no longer read IVR flows or the IVR call reports. If that admin is deactivated or leaves the organization, the key is suspended.

Create an API key

An organization admin creates a Queue CallBack API key in the portal, on the API keys page at https://dashboard.queuecallback.com/settings/api-keys. Only organization admins see the page; a User does not.

1. Sign in to the portal and open Settings.
2. On the API keys card, choose Manage API keys.
3. Choose Create API key. The dialog says: "The key acts for this organization with at most your rights, and only with the scopes you choose here."
4. In Name, say where the key is used, for example Claude Code - reporting (1 to 100 characters).
5. In Expires after, choose 30, 60, 90, 180 or 365 days. 90 days is preselected.
6. Under Scopes, choose at least one scope. The form groups them as IVR, Reporting, Callbacks, Queues and Organization, and shows each scope's description. It starts with the read scopes that take effect in your organization already selected, without pii:read. The Read only button brings back that same set. Nothing that writes, publishes or places calls is preselected. Clear removes every scope. Without the Custom IVR add-on the three IVR scopes are not offered, and a note under the list says why. See Scopes and Recommended key sets.
7. Choose Create key.
8. Copy the key from the next dialog: "Copy this key now and store it somewhere safe. It will not be shown again." Choose Copy, store the key (Store an API key safely), then choose Done.

Queue CallBack sends no reminder before a key expires, and a key's expiry cannot be changed after it is created. Check the Expires column, or api_key.expires_at in get_me, and rotate the key before that date.

The Create API key button is off when the organization already holds 25 active or suspended keys ("This organization has 25 of 25 active keys. Revoke one to create another.") or when Queue CallBack has switched API keys off for the whole service ("API keys are turned off on this server…"). In the second case existing keys can still be revoked, but not rotated, and every request with them is refused.

The key list shows each key as qcb_sk_...abcd (its last 4 characters), with the columns Name, Key, Scopes, Status, Created, Expires, Last used and Actions.

Store an API key safely

A Queue CallBack API key starts with qcb_sk_ and is 79 characters long. Anyone who holds it can use its scopes. Queue CallBack never stores the key itself, only a keyed hash of its secret part and, for display, its last 4 characters. A lost key cannot be shown again: rotate it instead.

• Keep the key in an environment variable such as QCB_API_KEY, set from a secret store. Client configurations refer to the variable, never to the key.
• Send the key only as Authorization: Bearer <key>, never in a URL.
• Never paste the key into a chat with an AI model, a ticket, an email, or a file you commit or share.
• Use one key per client and job, so you can revoke one without breaking the others. Separate keys do not add capacity: the organization's keys share one request limit.
• Use a variable name of your own; do not reuse one another tool reads, such as a name starting ANTHROPIC_.

Set the variable for the current terminal. Each command prompts for the key, so it never lands in your shell history.

# bash (Linux, Git Bash)
read -rs -p "Queue CallBack API key: " QCB_API_KEY && export QCB_API_KEY && echo

# zsh (the default shell on macOS)
read -rs "QCB_API_KEY?Queue CallBack API key: " && export QCB_API_KEY && echo

# Windows PowerShell 5.1 or PowerShell 7
$env:QCB_API_KEY = [System.Net.NetworkCredential]::new('', (Read-Host -AsSecureString 'Queue CallBack API key')).Password

To keep the key across sessions, store it in the operating system's secret store (macOS, Linux) and load it when a shell starts. On Windows, the simplest option is a user environment variable:

# macOS: store the key in the login keychain (prompts for it)
security add-generic-password -a "$USER" -s queuecallback-api-key -w
# Then add this line to ~/.zshrc or ~/.bash_profile; it holds no secret
export QCB_API_KEY="$(security find-generic-password -a "$USER" -s queuecallback-api-key -w)"

# Linux with libsecret: store the key (prompts for it)
secret-tool store --label='Queue CallBack API key' service queuecallback-api-key
# Then add this line to ~/.bashrc; it holds no secret
export QCB_API_KEY="$(secret-tool lookup service queuecallback-api-key)"

# Windows: save the key as a user environment variable (prompts for it). Windows stores it unencrypted in your user profile, where any program you run can read it. Open a new terminal afterwards.
[Environment]::SetEnvironmentVariable('QCB_API_KEY', [System.Net.NetworkCredential]::new('', (Read-Host -AsSecureString 'Queue CallBack API key')).Password, 'User')

After a rotation, store the new key over the old one. On macOS, run security add-generic-password -U -a "$USER" -s queuecallback-api-key -w (-U updates the existing item; without it the command fails because the item exists). On Linux, secret-tool store with the same attributes replaces the stored key. On Windows, run the SetEnvironmentVariable command again.

On a server or in CI, keep the key in the platform's secret store and expose it to the job as QCB_API_KEY.

Check that the variable holds a whole key without printing it. Each command prints 79:

echo "${#QCB_API_KEY}"

$env:QCB_API_KEY.Length

Some client commands expand the variable and save the key itself in the client's settings. Connect a client says which, per client.

What an API key can and cannot do

A Queue CallBack API key acts in exactly one organization: the one it was created in. No tool takes an organization id. On every request the key acts with at most the current rights of its creator, narrowed to its scopes and to the organization's settings (Custom IVR add-on, drafts, caller-data unmasking).

Queue CallBack can switch changes off on the server; while they are off, clients see only the read-only tools. After a change to a key, its scopes, the 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. Reconnect the client to refresh it. A change to the role of the admin who created the key can take a little longer, because the Queue CallBack API also reads that admin's rights through a short cache. Each tool call is checked again when it runs.

To see what a key can do now, call the get_me tool, which every key may call (Check the connection). scopes lists the scopes in effect:

{
  "actor_type": "api_key",
  "api_key": {
    "id": "<key id>",
    "name": "Claude Code - reporting",
    "prefix": "qcb_sk",
    "last4": "abcd",
    "created_at": "2026-11-05T09:00:00Z",
    "expires_at": "2027-02-03T09:00:00Z",
    "minted_by": "...<masked>"
  },
  "organization_id": "<organization id>",
  "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:<key id>"
}

An API key is a credential for the Queue CallBack MCP server. These pages document the MCP server only.

Scopes

A scope is one kind of access given to a Queue CallBack API key. There are 12. "What it allows" sums up each scope; the portal describes it in its own words. The IVR flow tools are Preview (IVR flows).

A queue is a Queue CallBack configuration connected to one RingCentral call queue; the portal lists queues under Configurations, where an organization admin creates them. The add_callback tool is listed only for keys whose pii:read takes effect. The tool reference gives the scopes of every tool.

How scopes are checked

• The Queue CallBack MCP server lists a tool only when the key holds every scope the tool needs, and the Queue CallBack API checks the same scopes again on every request.
• A tool the key lacks a scope for is not listed. A call to it by name is refused before anything is sent, with the tool error insufficient_scope and required_scope naming the scope.
• The Queue CallBack API can still refuse a listed tool with the tool error insufficient_scope, where required_scope names the missing scope. This happens when a scope stopped taking effect after the client fetched its tool list, or when a search by number or a caller filter is sent without an effective pii:read.
• A key's scopes are limited to its creator's role when it is created, and again on every request.

IVR call reports

The five IVR report tools (get_ivr_summary, list_ivr_calls, get_ivr_call, get_flow_decisions, list_ivr_flow_stats) need reports:read, and they are open only to organization admins of organizations with the Custom IVR add-on, or of organizations that keep IVR reporting for a time after the add-on lapsed. An API key counts as an organization admin while the admin who created it still is one. A sign-in counts when the signed-in person is an organization admin.

• get_me shows ivr_reporting_enabled. While it is false, the five tools are not listed, and a call to one is refused with ivr_reporting_not_enabled before anything is sent.
• The callback reports (get_callback_summary, list_callbacks), a callback's journey (get_callback_journey) and live numbers (get_live_stats) stay open to every role with reports:read.

When a scope does not take effect

The Custom IVR add-on is the IVR flow builder; the portal's Billing page sells it as the Custom IVA plan. Without it, the Create API key dialog does not offer the IVR scopes and says: "Needs the Custom IVR add-on (the IVR flow builder), which this organization does not have." While the plan can be bought, the reason reads: "Custom IVA is not active for this organization. An admin can buy or restore it on the Billing page." IVR scopes an existing key holds stay on it and work again if the add-on returns.

Other organization settings decide whether the remaining scopes take effect. While one is off, the portal gives the reason:

To turn on caller-data unmasking, an organization admin emails Queue CallBack support (support@queuecallback.com) with the organization's name. A healthcare-locked organization stays masked whatever is asked.

In the key list, a scope that is not in effect is struck through; hover it for the reason. A scope the creator's role no longer allows shows "Not allowed for the role of the admin who created this key."

Recommended key sets

Start with a read-only Queue CallBack API key, and put write scopes on separate API keys, one per job.

To add callbacks with add_callback, add pii:read to the callback operations key; it works only where caller-data unmasking is on. Adding a callback places real calls even without callbacks:dial: the queue rings and, once an agent answers, the customer is called.

Rotate, revoke and suspension

Organization admins rotate and revoke Queue CallBack API keys on the API keys page (Settings, then Manage API keys). Each key has one of four statuses:

Revoked and expired keys stay listed as records, so past changes stay attributable; tick Show revoked and expired keys (shown with a count once there is at least one) to see them. A refused key gets HTTP 401 invalid_token when a client connects, or the tool error invalid_credentials during a session (Errors).

Rotate an API key

Rotating creates a new key with the same name and scopes and stops the old key at once. Rotate before a key expires (see Expires), after a possible leak, or to take over a suspended key.

1. In the key's row, choose Rotate. The dialog says: "A new key with the same name and scopes is created and shown once, with you as its creator. The current key (qcb_sk_...abcd) stops working immediately: update every client that uses it."
2. In New key expires after, choose 30, 60, 90, 180 or 365 days.
3. Choose Rotate key and copy the new key. It is shown once.
4. Put the new key in QCB_API_KEY, or in the secret store it is loaded from, everywhere the old key was used, then reconnect each client.

• The rotating admin becomes the new key's creator, and its scopes are limited to that admin's role.
• Rotating an active or suspended key works at the 25-key limit, because the new key takes the old key's place. Rotating an expired key needs a free place: at 25 active or suspended keys it is refused ("This organization already has 25 active API keys; revoke one first"). A revoked key cannot be rotated.
• There is no overlap. To switch clients without a gap, create a new key, move the clients, then revoke the old key.

Revoke an API key

1. In the key's row, choose Revoke. The dialog says: "Requests with qcb_sk_...abcd are refused from now on. This cannot be undone."
2. Choose Revoke key.

Revoke a key when its client is retired or its user leaves. If a key may have leaked, rotate or revoke it at once; both stop it immediately. The Last used column shows keys nobody uses.

Automatic suspension

A key is suspended while the admin who created it is deactivated or no longer belongs to the organization. A suspended key is refused, still counts toward the 25-key limit, and works again if that admin is reactivated. Another admin can rotate it to take it over.

OAuth sign-in

OAuth sign-in lets Claude and ChatGPT connect to the Queue CallBack MCP server when a person signs in with their Queue CallBack account. No API key is needed. A signed-in connection is read-only: it acts as the person who signed in, in that person's own organization, limited by that person's role, and it can never change anything, place calls or show caller numbers unmasked. Every other client connects with an API key, and every task that changes something needs an API key.

This sign-in is not the portal's RingCentral Connection, which links Queue CallBack to RingCentral.

What you see when you sign in

1. Claude or ChatGPT opens the Queue CallBack sign-in page (https://dashboard.queuecallback.com/sign-in) in your browser.
2. Sign in with your Queue CallBack portal account. If you are already signed in to the portal in that browser, this step is skipped.
3. A consent page on https://accounts.dashboard.queuecallback.com asks you to allow the client to read your Queue CallBack data. ChatGPT also asks to see your name and email address (the standard openid, profile and email permissions); that gives it no further Queue CallBack access. Approve it.
4. You return to the client, which shows the Queue CallBack MCP server as connected and lists the read tools.

Checked with Claude and ChatGPT on 2026-11-06.

To check a signed-in connection, ask the client to call get_me. actor_type is oauth, user_id is your user id, api_key is null, role is your role, and scopes lists the read scopes in effect. Check the connection explains each field.

Sign-in or API key

To make changes from a Claude app, connect with an API key instead of signing in: Claude Desktop through the mcp-remote bridge, or a custom connector with the Request headers beta (Claude Desktop). ChatGPT cannot send an API key, so a ChatGPT chat stays read-only; for changes, use the Codex CLI or the OpenAI Responses API with an API key.

Disconnect or revoke sign-in

• Claude: open Customize > Connectors, then choose Remove, or the three dots next to the connector. On Team and Enterprise plans, an Owner removes an organization's connector under Organization settings > Connectors.
• ChatGPT: remove the Queue CallBack plugin in ChatGPT's plugin settings (Settings > Plugins).
• Removing the connection ends it in that client. An access token the client already holds stays valid until it expires, up to a day by default, and cannot be withdrawn earlier.
• A signed-in connection stops working within about a minute when the person is deactivated or leaves the organization in Queue CallBack.
• A change of role between Organization Admin and User applies to the person's sign-in on the next request: a User's sign-in has no ivr:read and no IVR call reports.

For client builders

The discovery document is https://mcp.queuecallback.com/.well-known/oauth-protected-resource/mcp (RFC 9728). It names the authorization server, accepts credentials only in the Authorization header, and lists all 12 scopes in scopes_supported because API keys can hold them. The 401 WWW-Authenticate challenge asks for the five read scopes, and a token that grants none of them gets 403 insufficient_scope. Access tokens must name https://mcp.queuecallback.com/mcp as their audience, so a token issued for another service is refused. Queue CallBack supports sign-in from Claude and ChatGPT only; other clients connect with an API key.

Related pages

• Connect a client: set up each AI client with QCB_API_KEY, or sign in from Claude or ChatGPT.
• Tools: every tool with its scopes.
• Safety: approval prompts, confirm tokens and caller-data masking.
• Errors and limits: every error code and its fix.
• Troubleshooting: symptom-first fixes and how to contact Queue CallBack support.