What you can change
The read tools you use to prepare a write are documented with the other read tools. Tool discovery lists the tools your granted scopes allow; your role and plan are checked when you call a tool.
Requirements
A write call needs all of the following.- A plan that includes MCP writes. An active Business, Agency Business or Enterprise plan, the same plans as REST writes. The Pitch Audit write tools also require an agency team. Reading through MCP is available from Starter, unchanged. This includes the read tools you use to prepare a write:
estimate_run,list_runs,get_run,get_credits,get_site_audit,get_prompt_suggestionsandget_prompt_suggestion_run. - The matching write scope. Granted by you, per connection. See Grant write scopes.
- The Manager or Owner role in the team. Each tool requires the minimum role of the equivalent dashboard action, which is Manager for every write. Members and Viewers read only.
Scopes
Roles
The role is the one you hold in the team that owns the workspace.get_credits also requires the Manager or Owner role, like the usage and credit pages of the dashboard.
Grant write scopes
On the OAuth consent screen, write scopes appear as options you tick yourself. Nothing is pre-selected. For a Personal Access Token, choose the write scopes when you create it under Team Management > MCP Server. See OAuth authentication for the full flow.- Grant only the scopes a task needs. A connection that prepares prompts does not need
write:monitoring. - To add a write scope to an existing connection, reconnect and authorize it again. Scopes are never expanded silently on an already-issued token.
- You can revoke a token at any time from Team Management > MCP Server.
How a write call works
1
Read the current state
Use the read tools to resolve IDs and read the
version of anything you plan to update.2
Preview with dryRun
Every write tool accepts
dryRun. With dryRun set to true, the tool validates the request and returns its effect, cost and warnings without changing anything.3
Confirm when required
When the tool’s confirmation rule applies, a call without a valid token returns the preview and a
confirmationToken and executes nothing. Review the preview, then call the same tool again with the same arguments and the token.4
Check the result
Read the resource again, or follow a run, audit or generation with its read tool.
dryRun
dryRun is a boolean that defaults to false. A dry run never changes data. Use it to check arguments, see what a bulk call would do to each item and see the cost of a paid action before you commit.
Preview and result
A write tool returns one of two shapes. A preview is returned instead of executing whendryRun is true, or when the confirmation rule applies and no valid confirmationToken was sent. Nothing has changed.
A result is returned after the change is applied.
A retry with the same
confirmationToken, or with the same intent, within 24 hours returns the same result without a second effect. replayed is then true.
If the outcome of a write is unknown (the connection dropped while it was committing), Qwairy never applies it twice:
- Tools that take an
expectedVersion,create_workspaceandconfirm_pitch_auditcan be retried at once: the version, the workspace domain or the audit state refuses a second effect. A retry applies the change, or reports what blocks it:VERSION_CONFLICT,CONFLICT,CONFIRMATION_INVALIDfor a used token (preview again), orversion_conflictitems in abulk_update_promptsresult. Read the resource to check. start_run,create_pitch_audit,create_prompts,create_topicandcreate_taghave no such guard. The same request answersRESOURCE_BUSYfor up to 5 minutes, then Qwairy settles it from its audit trail. If the change was applied, the same call with the sameconfirmationToken, or with a token from a preview requested while that call was in progress, replays it withreconciled: trueand the identifiers recorded (for examplerunId,auditIdor onepromptIdper created prompt). Acreate_promptsbatch that stopped part way, even on a refusal that listscreatedPromptIds, answersRESOURCE_BUSYthe same way, then lists the prompts it created and addsincompletewith the requested and applied counts: create the others with a new call. Otherwise, call the tool again.
start_run of the same prompts, is a new request and gets a new preview. Its warnings say whether confirming it replays an identical call still in progress, or applies again a request already applied within the last 24 hours.
expectedVersion
Update tools requireexpectedVersion: the version you last read for the resource. If the resource changed since, the call fails with a version conflict instead of overwriting the other change. Read the resource again and reconcile. Treat the value as opaque: do not compute the next version.
After a successful write, the version of the result is the one to use for the next change.
Where to read the version
For a
DRAFT, ARCHIVED or plan-locked workspace, call list_brands with includeInactive: true. For an archived prompt, call get_prompts with includeArchived: true.
The prompts, topics and tags of a DRAFT workspace cannot be read through MCP. Keep the versions returned when you create them, or activate the workspace before you edit them from another conversation.
bulk_update_prompts acts on several prompts and takes one version per prompt: expectedVersions, a map keyed by prompt ID.
Confirmation
Each tool has a confirmation rule, listed on its page.
Every tool that archives, rewrites, pauses or replaces existing data uses
always or except_restore. Topics and tags cannot be deleted through MCP: delete them from the dashboard or with the REST API.
A confirmation token:
- is returned with the preview of the call that needs it;
- can be used once;
- is valid for 10 minutes;
- is invalid if the arguments, the targets, their versions or the previewed cost change, so a changed request needs a new preview.
start_run, the token binds the exact plan you confirmed: the same prompts, texts, models, countries, personas and price. If any of them changed since the preview, nothing is reserved and the call returns CONFIRMATION_INVALID.
The confirmation step of your MCP client (Claude, ChatGPT or another) is an additional prompt. It does not replace the Qwairy token, and the Qwairy token does not replace the client’s approval.
Errors
A failed write returns one of these error codes.Credits
MCP calls themselves use no credits, and Qwairy applies no spending cap to MCP writes. Paid actions draw on the team credit balance exactly as they do from the dashboard:- starting a run;
- confirming a Pitch Audit;
- auditing pages;
- putting prompts under monitoring, which adds recurring credit use;
- a change that makes prompts due at once: a workspace going
LIVE, new or restored prompts, or automatic answers turned on. The next scheduler pass collects them, and the preview shows that cost incredits.oneOff.
get_credits and price a run with estimate_run. See Run and credit tools.
credits.dailyChange estimates the recurring monitoring you configure, including models that are temporarily unavailable or paused by Qwairy. Their collection can resume without another configuration change, so an increase still requires confirmation. Permanently disabled models, unsupported countries and premium models your team cannot use are excluded.
For monitoring changes, credits.oneOff reflects the collection that can start on the next scheduler pass. It excludes temporarily unavailable or paused collection paths. Neither estimate charges credits by itself.
Security
Qwairy limits this risk in several ways:- Write scopes are opt-in and separate from read scopes.
- Every tool checks your role and plan on the server.
- Previews show the effect, cost and warnings before anything changes.
- Sensitive and paid actions need a single-use confirmation token tied to the exact arguments.
dryRunlets you inspect any call without side effects.
Limits
- The assistant built into Qwairy stays read-only.
- Webhook endpoints and API keys are not managed through MCP. Use the REST API and the dashboard.
- Team membership, roles, credit transfers and purchases remain dashboard actions.
Next steps
Authorize write scopes
Consent, Personal Access Tokens and revocation.
Start with prompts
Create prompts, topics and tags with a preview.
Run a Pitch Audit
Follow the create, review and confirm flow.
Price a run
Estimate credits and follow run status.

