Skip to main content
Write tools let an MCP-compatible assistant change Qwairy data on your behalf: create prompts, update monitoring, start runs, run Pitch Audits and more. Every write goes through the same checks as the dashboard, plus a preview step and, for sensitive changes, a confirmation token.
Write access is opt-in. Write scopes are never granted by default, and tokens issued before write access existed stay read-only.

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_suggestions and get_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.
The REST API is a separate surface with its own plan and token settings. See Writing data.

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 when dryRun 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_workspace and confirm_pitch_audit can 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_INVALID for a used token (preview again), or version_conflict items in a bulk_update_prompts result. Read the resource to check.
  • start_run, create_pitch_audit, create_prompts, create_topic and create_tag have no such guard. The same request answers RESOURCE_BUSY for up to 5 minutes, then Qwairy settles it from its audit trail. If the change was applied, the same call with the same confirmationToken, or with a token from a preview requested while that call was in progress, replays it with reconciled: true and the identifiers recorded (for example runId, auditId or one promptId per created prompt). A create_prompts batch that stopped part way, even on a refusal that lists createdPromptIds, answers RESOURCE_BUSY the same way, then lists the prompts it created and adds incomplete with the requested and applied counts: create the others with a new call. Otherwise, call the tool again.
Calling an always-confirmed tool again without a token, such as a second 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 require expectedVersion: 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.
For 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 in credits.oneOff.
The preview shows the cost before you confirm. Check the balance with 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

Content an assistant reads can try to steer it. A web page, an AI answer, a competitor name or a prompt text may contain instructions aimed at the assistant (prompt injection). If the assistant follows them, it could call a write tool you did not intend.
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.
  • dryRun lets you inspect any call without side effects.
To reduce the risk further, grant the narrowest scopes, read each preview before you approve the client’s confirmation prompt, and revoke tokens you no longer use.

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.