---
title: "Safe changes"
section: "MCP & AI assistants"
description: "The SmartestQA MCP approval model: smartest_propose shows a diff and writes nothing, smartest_apply writes after you approve. Confirmation dialogs, removals, previews, languages."
url: https://docs.smartestqa.ai/en/mcp-safe-changes.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "propose apply diff preview approval stale_preview confirmation dialog remove admin read-only content language password data source key audit log mcp"
---
# MCP & AI assistants: Safe changes: propose, then apply

An assistant never changes a record in one step. It first shows you the change as a diff; only when you approve does it write exactly that. Some actions also need your click in a dialog.

## In short

**On this page you can**

- See every proposed change as a diff with its impact before anything is written.
- Approve a change in the chat, or ask the assistant to amend the draft.
- Confirm irreversible actions (removals, stopping runs, bulk sync) with a click.
- Keep passwords and tokens out of the chat with empty data source keys.

**How to use it**

1. Ask for the change in plain words.
2. Read the diff, the impact lines and any hints the assistant shows.
3. Say yes; the assistant applies that preview and nothing else.
4. For removals, confirm the dialog (Admins only).
5. Check the result in SmartestQA; admins see it in the audit log.

## How a change is approved

1. **The assistant drafts**

   From your request it builds a draft: for example two [modules](https://docs.smartestqa.ai/en/analyze-folders.html#modules), a [main requirement](https://docs.smartestqa.ai/en/analyze-requirements.html#create-main) with three [sub-requirements](https://docs.smartestqa.ai/en/analyze-requirements.html#sub-requirements), a [scenario plan](https://docs.smartestqa.ai/en/mcp-safe-changes.html#scenario-flow) or new [locators](https://docs.smartestqa.ai/en/discover-actions.html).
2. **It proposes**

   `smartest_propose` checks the draft against SmartestQA’s rules and your project, and returns a **diff** (what will be added, changed or removed), **impact** lines (what else it touches), **hints** and a **preview** id. It writes nothing.
3. **You read and decide**

   The assistant shows you the diff. Say yes, ask for a change (it amends the draft and proposes again), or say no.
4. **It applies**

   `smartest_apply` gets only the preview id and writes exactly what the diff showed. If the records changed since the preview, it refuses and proposes again.

   The records appear in SmartestQA. If the write stopped halfway (for example a connection error), the same preview finishes what is left.

Example · a diff as the assistant may show it (shortened)

```text
Proposed for project Web Shop:
+ MAIN  Checkout                 module: Orders
+ SUB   Pay with a saved card    under: Checkout
+ SUB   Card is declined         under: Checkout
Impact: 0 existing records change.
Apply this?
```

The same two-step rule applies to locators (`smartest_action_write`) and [auto-heal decisions](https://docs.smartestqa.ai/en/maintenance-auto-heal.html#review-a-repair) (`smartest_heal`): first a preview, then the write after you agree.

## Previews

| Situation | What happens |
| --- | --- |
| Applied once already | Refused with `STALE_PREVIEW`: “this preview was already applied. Nothing was written again”. |
| Records in scope changed since the preview | Refused with `STALE_PREVIEW`; the assistant proposes again and shows you the new diff. |
| Older than 30 minutes, or the MCP restarted | Refused: “the preview expired (30 minutes)”. Propose again. |
| A quality gate is not met | Refused with `HINT_UNMET`: “a gate is not met; propose again.” |
| Everything already matches | “Nothing to write: everything already matches.” |

A preview covers only the records it reads. A write in another main requirement does not make your preview stale.

## Actions that need your click

Some actions cannot be undone. For these the MCP server opens a confirmation dialog in your client, and the action runs only if you confirm it there. The assistant cannot click it for you.

| Action | Dialog says, for example |
| --- | --- |
| Removing records (intent **remove**) | “Will be permanently removed: … This cannot be undone.” Only an [**Admin**](https://docs.smartestqa.ai/en/company-settings-roles.html#matrix) can remove; others get “only an admin can remove records (your role: …); nothing was removed”. |
| Changing a record someone edited in SmartestQA after the MCP | “WARNING: … was edited by someone else after the MCP.” No Admin needed. |
| [Stopping a run](https://docs.smartestqa.ai/en/report-list.html#stop-a-run) | “Stop run … ? The running scenario finishes; the rest are skipped and show as FAILED. A stopped run cannot be resumed.” |
| Cancelling a self-hosted runner job that has not started yet, [mailing a report](https://docs.smartestqa.ai/en/report-summary.html#share-report) | A dialog naming the job or the address. A [dry run](https://docs.smartestqa.ai/en/automate-dry-run.html#close-panel) cannot be stopped. |
| Bulk sync to [Jira](https://docs.smartestqa.ai/en/integrations-issue-trackers.html#jira), [Xray](https://docs.smartestqa.ai/en/integrations-test-management.html#xray) or [Confluence](https://docs.smartestqa.ai/en/integrations-confluence.html) | “Send every unsynced record of project … ? This can create many issues or pages and cannot be undone.” |
| Running a writing SQL statement on a [database](https://docs.smartestqa.ai/en/data-source-connections.html#add-db) | A dialog with the statement. |

- If you decline: “NOT DONE - the user declined the confirmation dialog. Nothing was changed.” The assistant should not try again unless you ask.
- If your client cannot show dialogs: “NOT DONE - this action needs the user's click in a confirmation dialog and this connection cannot show one. Nothing was changed.” Do it in the SmartestQA screen, or from a client that shows dialogs.
- [Defects](https://docs.smartestqa.ai/en/tasks.html) cannot be deleted through MCP; they are [closed](https://docs.smartestqa.ai/en/tasks-statuses.html) with a note of what was done.

## Other safeguards

- **Your permissions.** Every call runs as [your SmartestQA user](https://docs.smartestqa.ai/en/company-settings-roles.html#matrix). The assistant reaches only [the projects you can reach](https://docs.smartestqa.ai/en/company-settings-users.html#project-access), and a call you are not allowed to make is refused.
- **No guessing the project.** Without a project, the first call lists your projects and the assistant must ask which one.
- **No passwords.** “Never ask for or write a password: credentials are datasource keys with empty values that the user fills in SmartestQA.” Steps and [API requests](https://docs.smartestqa.ai/en/api-requests.html) refer to them as [`{{ds:key}}`](https://docs.smartestqa.ai/en/data-source-in-tests.html#reference-syntax).
- **The right language.** Content (requirements, scenarios, steps, notes, documents) is written in the project’s language. A write in another language is refused. If the project has no language set, the assistant asks you and saves it.
- **Honest results.** A failed call is flagged as an error; the assistant must not report it as done.
- **Read-only installs.** A local install with `SMARTEST_READONLY=true` sees only reading tools. See [Update, list or remove](https://docs.smartestqa.ai/en/mcp-connect.html#manage).
- **Traceable.** [Changes made through MCP](https://docs.smartestqa.ai/en/logs-audit-log.html#mcp-changes) appear in **Configuration** › **Logs** › [**Audit logs**](https://docs.smartestqa.ai/en/logs-audit-log.html) (Admins) with the source **MCP (Claude)**. [Denied attempts](https://docs.smartestqa.ai/en/logs-audit-log.html#denied) are recorded too.

## The scenario flow in short

Writing tests has its own steps, so each scenario is approved twice: once as a plan, once as a green dry run.

1. **Plan**

   For a [sub-requirement](https://docs.smartestqa.ai/en/analyze-requirements.html#sub-requirements), the assistant proposes a scenario plan (`level=scenario`): for each scenario the rule it checks, the bug it would catch, its proof, and a step outline, plus any new [actions](https://docs.smartestqa.ai/en/discover-actions.html#manual-action) and [data keys](https://docs.smartestqa.ai/en/data-source-variables.html#create-key). You approve it with `smartest_apply`.
2. **Write and dry-run**

   `smartest_write_case` writes the steps and [runs them once](https://docs.smartestqa.ai/en/automate-dry-run.html), on the server or on your [online agent](https://docs.smartestqa.ai/en/agent-pool-agents.html#agent-status).
3. **Fix or decide**

   Red: it names the failed step and the likely cause, fixes and runs again. After three red runs the scenario is **BLOCKED** and the assistant asks you how to go on.
