> ## 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.

# Accès en écriture MCP

> Laissez un assistant MCP modifier vos données Qwairy avec des scopes d’écriture sur option, des aperçus dryRun, des versions et des jetons de confirmation.

Les outils d’écriture permettent à un assistant compatible MCP de modifier les données Qwairy en votre nom : créer des prompts, modifier le suivi, lancer des runs, exécuter des audits de prospection, et plus encore. Chaque écriture passe par les mêmes contrôles que le tableau de bord, plus une étape d’aperçu et, pour les modifications sensibles, un jeton de confirmation.

> [!WARNING]
>
> L’accès en écriture est activé sur option. Les scopes d’écriture ne sont jamais accordés par défaut, et les jetons émis avant l’arrivée de l’accès en écriture restent en lecture seule.

## Ce que vous pouvez modifier

| Domaine | Ce que font les outils | Page |
| - | - | - |
| Workspaces et suivi | Créer et modifier un workspace, modifier le suivi | [Workspaces et suivi](https://docs.qwairy.co/fr/mcp/write/workspaces-and-monitoring.md) |
| Prompts, Topics et Tags | Créer, modifier, archiver et modifier en masse des prompts ; gérer les Topics et les Tags | [Prompts, Topics et Tags](https://docs.qwairy.co/fr/mcp/write/prompts-topics-tags.md) |
| Runs | Lancer un run qui collecte des réponses immédiatement | [Runs](https://docs.qwairy.co/fr/mcp/write/runs.md) |
| Audits de prospection | Créer, relire et confirmer l’audit d’un prospect | [Audits de prospection](https://docs.qwairy.co/fr/mcp/write/pitch-audits.md) |
| Actions et site | Mettre à jour le statut d’une action, ajouter des pages, auditer des pages | [Actions et site](https://docs.qwairy.co/fr/mcp/write/actions-and-site.md) |
| Suggestions de prompts | Générer des suggestions et les accepter comme prompts | [Suggestions de prompts](https://docs.qwairy.co/fr/mcp/write/prompt-suggestions.md) |

Les outils de lecture dont vous vous servez pour préparer une écriture sont documentés avec les autres [outils de lecture](https://docs.qwairy.co/fr/mcp/tools/runs.md). La découverte liste les outils que vos scopes autorisent ; votre rôle et votre offre sont vérifiés à l’appel de l’outil.

## Prérequis

Un appel d’écriture exige tout ce qui suit.

* **Une offre qui inclut les écritures MCP.** Une offre Business, Agency Business ou Enterprise active, les mêmes offres que pour les écritures REST. Les outils d’écriture des audits de prospection exigent aussi une équipe agence. La lecture via MCP reste disponible à partir de Starter, sans changement. Cela inclut les outils de lecture dont vous vous servez pour préparer une écriture : `estimate_run`, `list_runs`, `get_run`, `get_credits`, `get_site_audit`, `get_prompt_suggestions` et `get_prompt_suggestion_run`.
* **Le scope d’écriture correspondant.** Accordé par vous, connexion par connexion. Consultez [Accorder des scopes d’écriture](#accorder-des-scopes-d’écriture).
* **Le rôle Manager ou Propriétaire dans l’équipe.** Chaque outil exige le rôle minimal de l’action équivalente du tableau de bord, qui est Manager pour toute écriture. Les Membres et les Lecteurs ne font que lire.

L’API REST est une surface distincte, avec ses propres réglages d’offre et de jeton. Consultez [Écrire des données](https://docs.qwairy.co/fr/developers/writing-data.md).

### Scopes

| Scope | Autorise |
| - | - |
| `write:workspaces` | Créer des workspaces, modifier leur profil et leur cycle de vie |
| `write:prompts` | Créer et modifier des prompts, des Topics et des Tags ; générer et accepter des suggestions de prompts |
| `write:monitoring` | Modifier les réglages de suivi et lancer des runs qui consomment des crédits |
| `write:pitch-audits` | Créer et confirmer des audits de prospection, qui consomment des crédits |
| `write:actions` | Modifier le statut des recommandations du Centre d’actions |
| `write:site` | Ajouter des pages suivies et lancer des audits de pages |

### Rôles

Le rôle est celui que vous détenez dans l’équipe propriétaire du workspace.

| Rôle | Outils d’écriture |
| - | - |
| Propriétaire, Manager | Tous les outils d’écriture |
| Membre, Lecteur | Aucun. Ces rôles utilisent seulement les outils de lecture |

`get_credits` exige aussi le rôle Manager ou Propriétaire, comme les pages d’utilisation et de crédits du tableau de bord.

## Accorder des scopes d’écriture

Sur l’écran de consentement OAuth, les scopes d’écriture apparaissent comme des options que vous cochez vous-même. Rien n’est présélectionné. Pour un jeton d’accès personnel, choisissez les scopes d’écriture lors de sa création dans **Gestion de l’équipe > Serveur MCP**. Consultez [Authentification OAuth](https://docs.qwairy.co/fr/mcp/oauth.md) pour le flux complet.

* N’accordez que les scopes dont une tâche a besoin. Une connexion qui prépare des prompts n’a pas besoin de `write:monitoring`.
* Pour ajouter un scope d’écriture à une connexion existante, reconnectez-vous et autorisez-la de nouveau. Les scopes d’un jeton déjà émis ne sont jamais étendus en silence.
* Vous pouvez révoquer un jeton à tout moment depuis **Gestion de l’équipe > Serveur MCP**.

## Comment fonctionne un appel d’écriture

**1. Lire l’état courant**

Utilisez les outils de lecture pour résoudre les identifiants et lire la `version` de tout ce que vous prévoyez de modifier.

**2. Prévisualiser avec dryRun**

Chaque outil d’écriture accepte `dryRun`. Avec `dryRun` défini sur `true`, l’outil valide la requête et renvoie son effet, son coût et ses avertissements sans rien modifier.

**3. Confirmer si nécessaire**

Lorsque la règle de confirmation de l’outil s’applique, un appel sans jeton valide renvoie l’aperçu et un `confirmationToken`, et n’exécute rien. Relisez l’aperçu, puis appelez de nouveau le même outil avec les mêmes arguments et le jeton.

**4. Vérifier le résultat**

Relisez la ressource, ou suivez un run, un audit ou une génération avec son outil de lecture.

### dryRun

`dryRun` est un booléen dont la valeur par défaut est `false`. Un dry run ne modifie jamais de données. Servez-vous-en pour vérifier des arguments, voir ce qu’un appel en masse ferait à chaque élément et connaître le coût d’une action payante avant de vous engager.

### Aperçu et résultat

Un outil d’écriture renvoie l’une de ces deux formes.

Un **aperçu** est renvoyé à la place de l’exécution lorsque `dryRun` vaut `true`, ou lorsque la règle de confirmation s’applique et qu’aucun `confirmationToken` valide n’a été envoyé. Rien n’a changé.

| Champ | Description |
| - | - |
| `executed` | Toujours `false` |
| `confirmationRequired` | `true` lorsque vous devez rappeler l’outil avec un jeton |
| `confirmationToken` | Le jeton à usage unique, ou `null` lorsqu’aucune confirmation n’est nécessaire |
| `expiresAt` | Date-heure ISO d’expiration du jeton, ou `null` |
| `effect` | Description en langage clair de ce qui changerait |
| `targets` | Les ressources résolues, chacune avec sa `version` courante |
| `credits.oneOff` | Entier. Crédits réservés ou débités une seule fois, y compris la collecte que le prochain passage du planificateur lance du fait du changement |
| `credits.dailyChange` | Nombre. Variation de la consommation quotidienne moyenne de crédits du suivi |
| `warnings` | Tableau de chaînes : points à examiner avant de confirmer |

Un **résultat** est renvoyé une fois la modification appliquée.

| Champ | Description |
| - | - |
| `executed` | Toujours `true` |
| `replayed` | `true` lorsque cet appel a renvoyé le résultat d’un appel identique précédent |
| `result` | Le corps de réponse de l’opération REST équivalente |
| `version` | Entier, nouvelle version de la ressource modifiée, ou `null` |

Une nouvelle tentative avec le même `confirmationToken`, ou avec la même intention, dans les 24 heures renvoie le même résultat sans second effet. `replayed` vaut alors `true`.

Si l’issue d’une écriture est inconnue (connexion coupée pendant l’enregistrement), Qwairy ne l’applique jamais deux fois :

* Les outils qui prennent un `expectedVersion`, `create_workspace` et `confirm_pitch_audit` peuvent être relancés tout de suite : la version, le domaine du workspace ou l’état de l’audit refuse un second effet. Une nouvelle tentative applique le changement, ou signale ce qui la bloque : `VERSION_CONFLICT`, `CONFLICT`, `CONFIRMATION_INVALID` pour un jeton déjà utilisé (prévisualisez à nouveau), ou des éléments `version_conflict` dans le résultat de `bulk_update_prompts`. Relisez la ressource pour vérifier.
* `start_run`, `create_pitch_audit`, `create_prompts`, `create_topic` et `create_tag` n’ont pas cette protection. La même demande répond `RESOURCE_BUSY` pendant 5 minutes au plus, puis Qwairy la règle à partir de son journal d’audit. Si le changement a été appliqué, le même appel avec le même `confirmationToken`, ou avec le jeton d’un aperçu demandé pendant que cet appel était en cours, le rejoue avec `reconciled: true` et les identifiants enregistrés (par exemple `runId`, `auditId` ou un `promptId` par prompt créé). Un lot `create_prompts` arrêté en cours de route, même sur un refus qui liste `createdPromptIds`, répond de même `RESOURCE_BUSY`, puis liste les prompts créés et ajoute `incomplete` avec les nombres demandé et appliqué : créez les autres avec un nouvel appel. Sinon, rappelez l’outil.

Rappeler sans jeton un outil toujours confirmé, comme un second `start_run` sur les mêmes prompts, est une nouvelle demande et donne un nouvel aperçu. Ses avertissements indiquent si le confirmer rejoue un appel identique encore en cours, ou applique à nouveau une demande déjà appliquée dans les dernières 24 heures.

### expectedVersion

Les outils de modification exigent `expectedVersion` : la `version` que vous avez lue en dernier pour la ressource. Si la ressource a changé depuis, l’appel échoue avec un conflit de version au lieu d’écraser l’autre modification. Relisez la ressource et réconciliez. Traitez la valeur comme opaque : ne calculez pas la version suivante.

Après une écriture réussie, la `version` du résultat est celle à utiliser pour la modification suivante.

#### Où lire la version

| Outil | Outil de lecture | Champ |
| - | - | - |
| `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` |

Pour un workspace `DRAFT`, `ARCHIVED` ou bloqué par l’offre, appelez `list_brands` avec `includeInactive: true`. Pour un prompt archivé, appelez `get_prompts` avec `includeArchived: true`.

Les prompts, topics et tags d’un workspace `DRAFT` ne sont pas lisibles par MCP. Conservez les versions renvoyées à leur création, ou activez le workspace avant de les modifier depuis une autre conversation.

`bulk_update_prompts` agit sur plusieurs prompts et prend une version par prompt : `expectedVersions`, une table indexée par identifiant de prompt.

### Confirmation

Chaque outil a une règle de confirmation, indiquée sur sa page.

| Règle | Quand un jeton de confirmation est exigé |
| - | - |
| `never` | Jamais. L’outil s’exécute directement, sauf si `dryRun` vaut `true` |
| `always` | À chaque exécution |
| `except_restore` | À chaque exécution, sauf une simple restauration d’éléments archivés qui n’augmente pas la consommation de crédits |
| `cost_increase` | Lorsque la modification lance ou augmente une consommation de crédits récurrente ou ponctuelle |
| `go_live` | Lorsque la modification fait passer un workspace en `LIVE` |

Tout outil qui archive, réécrit, met en pause ou remplace des données existantes utilise `always` ou `except_restore`. Les Topics et les Tags ne peuvent pas être supprimés via MCP : supprimez-les depuis le tableau de bord ou avec l’API REST.

Un jeton de confirmation :

* est renvoyé avec l’aperçu de l’appel qui en a besoin ;
* ne peut servir qu’une seule fois ;
* est valable 10 minutes ;
* devient invalide si les arguments, les cibles, leurs versions ou le coût prévisualisé changent : une requête modifiée exige donc un nouvel aperçu.

Pour `start_run`, le jeton engage exactement le plan confirmé : mêmes prompts, textes, modèles, pays, personas et prix. Si l’un d’eux a changé depuis l’aperçu, rien n’est réservé et l’appel renvoie `CONFIRMATION_INVALID`.

L’étape de confirmation de votre client MCP (Claude, ChatGPT ou un autre) est une demande supplémentaire. Elle ne remplace pas le jeton Qwairy, et le jeton Qwairy ne remplace pas l’approbation du client.

## Erreurs

Une écriture en échec renvoie l’un de ces codes d’erreur.

| Code | Signification |
| - | - |
| `INVALID_REQUEST` | Les arguments ne passent pas la validation |
| `NOT_FOUND` | Le workspace ou la ressource n’existe pas pour cette équipe, ou vous ne pouvez pas le voir |
| `INSUFFICIENT_SCOPE` | Le jeton n’a pas le scope d’écriture. Reconnectez-vous et accordez-le |
| `INSUFFICIENT_ROLE` | Votre rôle dans cette équipe est inférieur au rôle minimal de l’outil |
| `PLAN_REQUIRED` | L’offre de l’équipe n’inclut pas les écritures MCP ou cet outil |
| `WRITES_DISABLED` | Qwairy a suspendu les écritures pour cette famille d’outils |
| `CONFIRMATION_REQUIRED` | L’outil a besoin d’un `confirmationToken` issu d’un aperçu |
| `CONFIRMATION_INVALID` | Le jeton est inconnu, déjà utilisé ou expiré, ou ne correspond plus aux arguments, aux cibles, aux versions ou au coût. Prévisualisez de nouveau |
| `VERSION_CONFLICT` | La ressource a changé depuis la lecture de `expectedVersion` |
| `CONFLICT` | La modification entre en conflit avec l’état actuel, par exemple un nom en double ou une transition non autorisée |
| `INSUFFICIENT_CREDITS` | Le solde de l’équipe ne couvre pas l’action |
| `QUOTA_EXCEEDED` | Une limite d’offre, de workspace ou de génération est atteinte |
| `RESOURCE_BUSY` | Une autre opération détient la ressource, ou l’issue de la même demande n’est pas encore connue. Réessayez plus tard |
| `RATE_LIMITED` | Trop d’écritures pour cette équipe. Le quota d’écriture est partagé avec l’API REST |

## Crédits

Les appels MCP eux-mêmes ne consomment aucun crédit, et Qwairy n’applique aucun plafond de dépense aux écritures MCP. Les actions payantes puisent dans le solde de crédits de l’équipe exactement comme depuis le tableau de bord :

* lancer un run ;
* confirmer un audit de prospection ;
* auditer des pages ;
* mettre des prompts sous suivi, ce qui ajoute une consommation de crédits récurrente ;
* un changement qui rend des prompts dus tout de suite : un workspace qui passe `LIVE`, des prompts créés ou restaurés, ou les réponses automatiques activées. Le prochain passage du planificateur les collecte, et l’aperçu indique ce coût dans `credits.oneOff`.

L’aperçu indique le coût avant que vous confirmiez. Vérifiez le solde avec `get_credits` et chiffrez un run avec `estimate_run`. Consultez [Outils de runs et de crédits](https://docs.qwairy.co/fr/mcp/tools/runs.md).

`credits.dailyChange` estime le suivi récurrent que vous configurez, y compris les modèles temporairement indisponibles ou mis en pause par Qwairy. Leur collecte peut reprendre sans nouvelle modification de configuration : une augmentation exige donc toujours votre confirmation. Les modèles désactivés de façon permanente, les pays non pris en charge et les modèles premium auxquels votre équipe n’a pas accès sont exclus.

Pour les modifications du suivi, `credits.oneOff` correspond à la collecte qui peut démarrer au prochain passage du planificateur. Les modes de collecte temporairement indisponibles ou en pause sont exclus. Aucune de ces estimations ne débite de crédits par elle-même.

## Sécurité

> [!WARNING]
>
> Le contenu qu’un assistant lit peut tenter de l’orienter. Une page web, une réponse d’IA, le nom d’un concurrent ou le texte d’un prompt peut contenir des instructions destinées à l’assistant (injection de prompt). S’il les suit, il pourrait appeler un outil d’écriture que vous n’aviez pas prévu.

Qwairy limite ce risque de plusieurs façons :

* Les scopes d’écriture sont activés sur option et séparés des scopes de lecture.
* Chaque outil vérifie votre rôle et votre offre côté serveur.
* Les aperçus montrent l’effet, le coût et les avertissements avant tout changement.
* Les actions sensibles et payantes exigent un jeton de confirmation à usage unique, lié aux arguments exacts.
* `dryRun` permet d’examiner n’importe quel appel sans effet de bord.

Pour réduire encore le risque, accordez les scopes les plus étroits, lisez chaque aperçu avant d’approuver la demande de confirmation du client, et révoquez les jetons que vous n’utilisez plus.

## Limites

* L’assistant intégré à Qwairy reste en lecture seule.
* Les endpoints de webhook et les clés d’API ne se gèrent pas via MCP. Utilisez l’[API REST](https://docs.qwairy.co/fr/developers/writing-data.md) et le tableau de bord.
* L’appartenance à l’équipe, les rôles, les transferts de crédits et les achats restent des actions du tableau de bord.

## Étapes suivantes

> [card] [Autoriser les scopes d’écriture](https://docs.qwairy.co/fr/mcp/oauth.md)
>
> Consentement, jetons d’accès personnels et révocation.

> [card] [Commencer par les prompts](https://docs.qwairy.co/fr/mcp/write/prompts-topics-tags.md)
>
> Créez des prompts, des Topics et des Tags avec un aperçu.

> [card] [Lancer un audit de prospection](https://docs.qwairy.co/fr/developers/guides/pitch-audit-prospect-mcp.md)
>
> Suivez le flux de création, de relecture et de confirmation.

> [card] [Chiffrer un run](https://docs.qwairy.co/fr/mcp/tools/runs.md)
>
> Estimez les crédits et suivez l’état des runs.


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