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

# Add prompt suggestions with MCP

> Generate Prompt Studio suggestions from an MCP assistant, review them, accept the ones you want after a cost preview, and follow prompt_suggestions.ready.

Prompt Studio proposes prompts to monitor. This guide generates a pool of suggestions from an MCP assistant, reviews them with you, and accepts the selected ones as prompts. Generation uses no customer credits. Accepting monitored prompts adds recurring credit use, and can start one collection at the next scheduler pass.

## Before you start

* An active Business, Agency Business or Enterprise plan.
* A connection with `read:prompts` and `write:prompts`, and a Manager or Owner role. See [MCP write access](https://docs.qwairy.co/mcp/write/overview.md).
* A workspace, with its topics already created if you want a generation per topic.

## Steps

**1. Start a generation**

The assistant calls [`generate_prompt_suggestions`](https://docs.qwairy.co/mcp/write/prompt-suggestions#generate_prompt_suggestions). Use `source: manual` for the whole workspace, or `source: topic` with a `keywordId`:

```json theme={null}
{ "brandId": "brand_01", "source": "topic", "keywordId": "topic_01", "requestId": "suggestions-001" }
```

A workspace can start 3 workspace generations and 10 topic generations over a rolling 24 hours, with at most one workspace generation and one per topic running at a time. Reuse `requestId` for a lost response; change it for a new generation, including after `FAILED`.

**2. Wait for it to finish**

The assistant polls [`get_prompt_suggestion_run`](https://docs.qwairy.co/mcp/tools/responses#get_prompt_suggestion_run) until the status is `COMPLETED`. A client that also uses the REST API can subscribe to [`prompt_suggestions.ready`](https://docs.qwairy.co/developers/integration-webhooks/events#prompt_suggestions-ready) and [`prompt_suggestions.failed`](https://docs.qwairy.co/developers/integration-webhooks/events#prompt_suggestions-failed) instead of polling. The event carries the generation ID in `data.runId`.

**3. Read the suggestions**

[`get_prompt_suggestions`](https://docs.qwairy.co/mcp/tools/responses#get_prompt_suggestions) returns the 20 recommendations by default, with a `score`, a `reason` and a `tracked` flag. Pass `limit`, up to 500, to read more of the pool; `total` gives its size. Use `focus` to reorder by funnel stage: `DISCOVERY`, `CONSIDERATION`, `PERCEPTION` or `AUTHORITY`. Skip suggestions that are already tracked, which means active and monitored. A suggestion equivalent to an archived or paused prompt reads `false`, and accepting it reactivates that prompt.

**4. Choose and preview**

Pick up to 20 suggestions. The assistant calls [`accept_prompt_suggestions`](https://docs.qwairy.co/mcp/write/prompt-suggestions#accept_prompt_suggestions) with `dryRun` set to `true`, or without a token:

```json theme={null}
{
  "brandId": "brand_01",
  "suggestionIds": ["suggestion_01", "suggestion_02"],
  "keywordId": "topic_01",
  "monitoringEnabled": true
}
```

Qwairy returns the outcome of each suggestion, the recurring credit use of the monitored prompts in `credits.dailyChange`, the cost of the collection the next scheduler pass would start in `credits.oneOff`, and a `confirmationToken`.

**5. Confirm**

If both amounts are acceptable, confirm. The assistant repeats the call with the same arguments and the token. The token is single use, valid for 10 minutes, and rejected if the arguments or the cost changed. Your MCP client may ask for its own approval too.

**6. Check the prompts**

List the prompts of the workspace and confirm the new ones are there with the expected topic and monitoring state.

## Example conversation

```text theme={null}
You: Suggest prompts for our CRM software topic.

Assistant: starts a topic generation, waits for it, then shows the five
highest-scored suggestions that are not already tracked.

You: Take the first three, monitored weekly.

Assistant: previews the acceptance. Three prompts would be created, with their
recurring credit use and a confirmation token.

You: Confirm.

Assistant: accepts with the token and lists the new prompts.
```

## Limits

* Suggestions are ideas based on your workspace. They do not predict what an AI assistant will answer.
* Accepting uses suggestions of the latest generation. IDs are bound to content and taxonomy: read them again after regeneration, and never construct them yourself.
* A suggestion can be created, already tracked, not found or invalid: check every item.
* Accepting starts no collection itself, but on a `LIVE` workspace it can make new or reactivated prompts due at the next scheduler pass. That collection uses credits once; the preview shows the amount in `credits.oneOff`.

## Related

* [Prompt suggestion write tools](https://docs.qwairy.co/mcp/write/prompt-suggestions.md)
* [Generate prompt suggestions](https://docs.qwairy.co/developers/endpoints/prompt-suggestions/generate.md) for the REST equivalent.


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