> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP write access

> Let an MCP assistant change Qwairy data with opt-in write scopes, role checks, dryRun previews, version checks and single-use confirmation tokens.

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.

> [!WARNING]
>
> 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

| Area | What the tools do | Page |
| - | - | - |
| Workspaces and monitoring | Create and update a workspace, change monitoring | [Workspaces and monitoring](https://docs.qwairy.co/mcp/write/workspaces-and-monitoring.md) |
| Prompts, topics and tags | Create, update, archive and bulk-edit prompts; manage topics and tags | [Prompts, topics and tags](https://docs.qwairy.co/mcp/write/prompts-topics-tags.md) |
| Runs | Start a run that collects answers now | [Runs](https://docs.qwairy.co/mcp/write/runs.md) |
| Pitch Audits | Create, review and confirm a prospect audit | [Pitch Audits](https://docs.qwairy.co/mcp/write/pitch-audits.md) |
| Actions and site | Update an action status, add pages, audit pages | [Actions and site](https://docs.qwairy.co/mcp/write/actions-and-site.md) |
| Prompt suggestions | Generate suggestions and accept them as prompts | [Prompt suggestions](https://docs.qwairy.co/mcp/write/prompt-suggestions.md) |

The read tools you use to prepare a write are documented with the other [read tools](https://docs.qwairy.co/mcp/tools/runs.md). 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](#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](https://docs.qwairy.co/developers/writing-data.md).

### Scopes

| Scope | Allows |
| - | - |
| `write:workspaces` | Create workspaces, change their profile and lifecycle |
| `write:prompts` | Create and change prompts, topics and tags; generate and accept prompt suggestions |
| `write:monitoring` | Change monitoring settings and start runs that use credits |
| `write:pitch-audits` | Create and confirm Pitch Audits, which use credits |
| `write:actions` | Change the status of Action Center recommendations |
| `write:site` | Add monitored pages and start page audits |

### Roles

The role is the one you hold in the team that owns the workspace.

| Role | Write tools |
| - | - |
| Owner, Manager | Every write tool |
| Member, Viewer | None. These roles use the read tools only |

`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](https://docs.qwairy.co/mcp/oauth.md) 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.

| Field | Description |
| - | - |
| `executed` | Always `false` |
| `confirmationRequired` | `true` when you must call again with a token |
| `confirmationToken` | The single-use token, or `null` when no confirmation is needed |
| `expiresAt` | ISO date-time at which the token expires, or `null` |
| `effect` | Plain description of what would change |
| `targets` | The resolved resources, each with its current `version` |
| `credits.oneOff` | Integer. Credits reserved or debited once, including the collection the next scheduler pass starts because of the change |
| `credits.dailyChange` | Number. Change in the average daily credit use of monitoring |
| `warnings` | String array of points to review before you confirm |

A **result** is returned after the change is applied.

| Field | Description |
| - | - |
| `executed` | Always `true` |
| `replayed` | `true` when this call returned the result of an earlier identical call |
| `result` | The response body of the equivalent REST operation |
| `version` | Integer, the new version of the changed resource, or `null` |

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

| Tool | Read tool | Field |
| - | - | - |
| `update_workspace` | `list_brands` | `workspaces[].version` |
| `update_monitoring` | `list_brands` | `workspaces[].monitoring.version` |
| `update_prompt`, `bulk_update_prompts` | `get_prompts` | `prompts[].version` |
| `update_topic` | `list_topics` | `topics[].version` |
| `update_tag` | `list_tags` | `tags[].version` |
| `save_pitch_audit_prompts` | `get_pitch_audit` | `version` |
| `update_action_status` | `get_actions` | `actions[].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.

| Rule | When a confirmation token is required |
| - | - |
| `never` | Never. The tool executes directly unless `dryRun` is `true` |
| `always` | Every execution |
| `except_restore` | Every execution, except a plain restore of archived items that does not raise credit use |
| `cost_increase` | When the change starts or increases recurring or one-off credit use |
| `go_live` | When the change moves a workspace to `LIVE` |

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.

| Code | Meaning |
| - | - |
| `INVALID_REQUEST` | The arguments fail validation |
| `NOT_FOUND` | The workspace or resource does not exist for this team, or you cannot see it |
| `INSUFFICIENT_SCOPE` | The token lacks the write scope. Reconnect and grant it |
| `INSUFFICIENT_ROLE` | Your role on this team is below the minimum role of the tool |
| `PLAN_REQUIRED` | The team plan does not include MCP writes or this tool |
| `WRITES_DISABLED` | Qwairy has paused writes for this tool family |
| `CONFIRMATION_REQUIRED` | The tool needs a `confirmationToken` from a preview |
| `CONFIRMATION_INVALID` | The token is unknown, already used or expired, or no longer matches the arguments, targets, versions or cost. Preview again |
| `VERSION_CONFLICT` | The resource changed since `expectedVersion` was read |
| `CONFLICT` | The change conflicts with the current state, for example a duplicate name or a transition that is not allowed |
| `INSUFFICIENT_CREDITS` | The team balance cannot cover the action |
| `QUOTA_EXCEEDED` | A plan, workspace or generation limit is reached |
| `RESOURCE_BUSY` | Another operation holds the resource, or the outcome of the same request is not known yet. Retry later |
| `RATE_LIMITED` | Too many writes for this team. The write quota is shared with the REST API |

## 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](https://docs.qwairy.co/mcp/tools/runs.md).

`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

> [!WARNING]
>
> 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](https://docs.qwairy.co/developers/writing-data.md) and the dashboard.
* Team membership, roles, credit transfers and purchases remain dashboard actions.

## Next steps

> [card] [Authorize write scopes](https://docs.qwairy.co/mcp/oauth.md)
>
> Consent, Personal Access Tokens and revocation.

> [card] [Start with prompts](https://docs.qwairy.co/mcp/write/prompts-topics-tags.md)
>
> Create prompts, topics and tags with a preview.

> [card] [Run a Pitch Audit](https://docs.qwairy.co/developers/guides/pitch-audit-prospect-mcp.md)
>
> Follow the create, review and confirm flow.

> [card] [Price a run](https://docs.qwairy.co/mcp/tools/runs.md)
>
> Estimate credits and follow run status.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.