# MCP triggers

> For the complete documentation index, see [llms.txt](https://promptless.ai/llms.txt).

Connect Claude Code, Cursor, Claude, or another MCP client to Promptless to start, track, and revise documentation tasks, or to edit your docs directly. Authorize with OAuth. No API key needed.

## Overview

Connect Claude Code, Cursor, Claude, or another MCP client to Promptless. From the conversation you already have open, start a documentation task and get back its outcome and docs pull request link. You can also send a running task more instructions, ask Promptless to revise a suggestion, and label, assign, retitle, open, or close a suggestion. You authorize once in a browser, with no API key to manage.

[MCP](https://modelcontextprotocol.io) is an open protocol that editors use to connect to external tools. Any editor with an "MCP servers" setting can connect to Promptless. The Promptless MCP server is built in and always available, with no `promptless.yaml` `triggers:` entry and no setup on the Configuration page.

  MCP is the no-key, interactive editor path. The [API trigger](https://promptless.ai/docs/for-docs/connect/triggers/api) is the server-to-server and CI path: an API key plus `POST /v1/triggers`. Both dispatch through the same pipeline, so a task behaves identically whichever way you start it.

To use Promptless from the Claude.ai or ChatGPT web app, follow [Use Promptless from Claude.ai or ChatGPT](https://promptless.ai/docs/for-docs/work-the-queue/claude-and-chatgpt).

## Before you start

- An MCP-capable editor, such as Claude Code or Cursor, or a chat app that accepts custom connectors, such as Claude.
- Your organization's [Promptless setup](https://app.gopromptless.ai/configuration) finished.
- An active membership in the organization. MCP needs no API key and no particular organization role.

## Connect the server

Promptless has two server URLs:

- `https://api.gopromptless.ai/mcp` is the standard server. Promptless drafts the documentation changes, and you review them. Use it day to day.
- `https://api.gopromptless.ai/mcp/with-direct-edits` adds six tools so your client can [edit doc files itself](#read-and-edit-documentation-directly). The extra tools use more of your client's context, so switch to `/mcp` once you no longer need to edit files directly.

Each URL is a separate connection that you authorize on its own. The steps below use `/mcp`; use the direct-edit URL in its place to get the extra tools.

Connect the server once per editor. For Claude Code, one command sets it up:

```bash
claude mcp add --transport http promptless https://api.gopromptless.ai/mcp
```

The same URL and command also appear in the [dashboard](https://app.gopromptless.ai) under **Settings**, in the **Editor connection (MCP)** section, which every organization member can see.

### Claude Code

  1. Run the add command shown above.

  2. Run `/mcp` and pick **promptless**.

  3. Authorize the connection in the browser tab that opens. See [Authorize in the browser](#authorize-in-the-browser).

### Cursor

  1. Add an HTTP MCP server named `promptless`. Use the URL `https://api.gopromptless.ai/mcp`, either in Cursor's MCP settings or by adding the entry to `mcp.json`:

     ```json
     {
       "mcpServers": {
         "promptless": {
           "url": "https://api.gopromptless.ai/mcp"
         }
       }
     }
     ```

     The `url` key tells Cursor to use HTTP transport. Or add the server in one step with the [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=promptless\&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vYXBpLmdvcHJvbXB0bGVzcy5haS9tY3AifQ%3D%3D) deep link, which registers the `promptless` server for you.

  2. Click **Needs login**.

  3. Authorize the connection in the browser tab that opens. See [Authorize in the browser](#authorize-in-the-browser).

### VS Code

  1. Add the `promptless` server with the `code` CLI:

     ```bash
     code --add-mcp "{\"name\":\"promptless\",\"type\":\"http\",\"url\":\"https://api.gopromptless.ai/mcp\"}"
     ```

  2. Run **MCP: List Servers** from the Command Palette and start **promptless**.

  3. Authorize the connection in the browser tab that opens. See [Authorize in the browser](#authorize-in-the-browser).

### Codex CLI

  1. Add the `promptless` server; Codex infers HTTP transport from the `--url` flag:

     ```bash
     codex mcp add promptless --url https://api.gopromptless.ai/mcp
     ```

  2. Run `codex mcp login promptless` to start authorization.

  3. Authorize the connection in the browser tab that opens. See [Authorize in the browser](#authorize-in-the-browser).

### Claude

Add Promptless to Claude as a [custom connector](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp):

  1. In Claude, open **Customize** > **Connectors**, select **+**, then select **Add custom connector**.

  2. Enter `https://api.gopromptless.ai/mcp`, then select **Add**.

  3. Select **Connect**, and authorize the connection in the browser tab that opens. See [Authorize in the browser](#authorize-in-the-browser).

On a Team or Enterprise plan, an Owner adds the connector under **Organization settings** > **Connectors**, then each member selects **Connect** in **Customize** > **Connectors**. Turn the connector on for a conversation from the **+** menu under **Connectors**.

### Other MCP clients

Any client that supports HTTP transport and OAuth connects at either URL. The exact steps vary by client.

## Authorize in the browser

Your editor handles authorization automatically over OAuth; you approve the connection once in the browser.

  1. A browser tab opens to the Promptless consent page.

  2. Choose the organization to connect. The picker defaults to your active organization.

  3. Check the **Returns to** row. It shows where Promptless sends access when you approve. Promptless doesn't verify the client name, so go by this row. A local editor such as Claude Code or Cursor returns to a local address with a port, like `127.0.0.1:54321`. An app that opens through its own link scheme shows a callback like `myapp://claude.ai/cb`, and any app on your device that handles `myapp://` links receives the access. Cancel if you didn't start this connection from that editor or app.

  4. Select **Authorize as \{your email}**. Your editor stores the token and returns you to the editor.

  An approved client acts with the same access as the member who approved it. The consent page has no permission picker. An approved connection can:

  - Start tasks, and send an additional instruction into a running task.
  - List your collections and your recent tasks, and search suggestions.
  - Read the status of any task in your organization, and follow a running one to its outcome. This includes tasks started from Slack, a GitHub pull request, the dashboard, or the API.
  - Revise a suggestion Promptless already produced.
  - Update a suggestion's labels, assignees, and title, and open its docs pull request.
  - Close a suggestion, which also closes its docs pull request.
  - On the direct-edit URL, read and search your documentation and commit edits to an open suggestion's branch.

  The write actions (revise, update, close, and edit) act on any suggestion in your organization, like the read tools, including suggestions other members created. Any active organization member can authorize a connection, whatever their [organization role](https://promptless.ai/docs/for-docs/security/access-and-permissions), and MCP access can't be limited to specific members or roles. To control what gets submitted, use your [publishing policies and relevance filtering](https://promptless.ai/docs/for-docs/tune/noise-and-relevance-filtering).

A token is tied to one organization. When your client names the server URL in its authorization request, the token works only at that URL. When it doesn't, the token works at both URLs, so the consent screen lists file reading and editing for every connection. To connect a second organization, authorize again and pick that organization at consent. Your editor can hold one Promptless connection per organization.

## Available tools

Both server URLs carry these 11 tools, which let you check on your collections, tasks, and suggestions, or queue and change your documentation work. The direct-edit URL adds six more, described in [Read and edit documentation directly](#read-and-edit-documentation-directly). Five tools are read-only: `list_doc_collections`, `get_task_status`, `list_recent_tasks`, `search_suggestions`, and `wait_for_task_update`. Your editor can auto-approve them, so routine status checks stop prompting you each time. Six tools queue or change work: `submit_documentation_task`, `send_task_message`, `answer_task_question`, `request_changes`, `update_suggestion`, and `close_suggestion`. These always ask before they run.

  If you already have an MCP connection, refresh or reconnect the `promptless` server in your editor. That loads the `send_task_message`, `answer_task_question`, and `wait_for_task_update` tools, the current tool descriptions, and the `next_call` that `submit_documentation_task` and `request_changes` return for following the task. In Claude Code, run `/mcp` and pick **promptless** again, or start a new conversation. In Cursor, remove the `promptless` server and add it again.

### `submit_documentation_task`

Starts a documentation task and returns a task ID (the `trigger_event_id`) you can check with `get_task_status`. It also returns a `next_call`, the next tool call your editor should make. It names `wait_for_task_update` with its arguments, so your editor can follow the task automatically.

| Argument            | Required | Description                                                                                                                                                                                                                 |
| ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `instructions`      | Yes      | What you want documented.                                                                                                                                                                                                   |
| `doc_collection_id` | No       | Target one collection. Omit to route across all your collections.                                                                                                                                                           |
| `context`           | No       | Optional metadata attached to the request; appears in trigger history.                                                                                                                                                      |
| `attachments`       | No       | Links to material that explains the change, such as a screenshot, design file, or spec. Each attachment is a URL (required) with an optional description; nothing is uploaded, so a link Promptless can't reach is skipped. |

A request that routes across all your collections still applies your [relevance filtering](https://promptless.ai/docs/for-docs/tune/noise-and-relevance-filtering) per collection. To target one collection, pass a `doc_collection_id` from `list_doc_collections`.

A run takes several minutes. The submission returns a `next_call`, and your editor follows the task with `wait_for_task_update` until `next_call` is null. The outcome appears in the same conversation. To check status at a point in time, call `get_task_status` on request. To find a task later, use `list_recent_tasks`, which also lists tasks you didn't start over MCP.

### `list_doc_collections`

Lists your documentation collections. Use it to get a `doc_collection_id` to pass to `submit_documentation_task`.

### `get_task_status`

Checks the status of any documentation task in your organization by its `trigger_event_id`, not only tasks you submitted over MCP. Tasks started from Slack, a GitHub pull request, the dashboard, or the API are all readable. The task's submitted instructions and context appear in its trigger history.

It also returns the suggestions the task produced. Each comes with its docs pull request link and review status, using the same `draft`, `open`, `merged`, or `closed` values `search_suggestions` uses. The response says whether the task has finished. Once it has, `outcome` says how it ended: `suggestions_created`, `no_change_needed`, `needs_input`, or `failed`. `outcome` is `null` until the task finishes, and for tasks from sources other than the API or MCP. A `resolution` note explains how the task ended.

It also returns the task's conversation. The `messages` array is the persisted conversation between the customer and Promptless for that task, capped at the latest 100 messages and returned oldest-first. The `messages` array is populated for tasks submitted over the API or MCP and for tasks created by calling `request_changes` over MCP. An empty `messages` array means either the task has no messages yet or its source doesn't carry a conversation. Reading the conversation never consumes it.

Each message carries a stable, immutable `id`, a `sequence` number, an `author` object, a `created_at`, and the `message` text. The `id` lets a caller dedupe, relaying each new message only once. Your editor tracks these `id`s for you, so it doesn't relay the same message twice. Incremental message delivery comes from `wait_for_task_update`'s `cursor`. `get_task_status` reads the conversation so far at a single point in time. The `author` object's `type` is `promptless` or `customer`, and its `name` is the customer's email when available, otherwise null.

A `status_guidance` field is a short text string carrying server-generated advice about following the task and interpreting its outcome. That advice is distinct from the conversation itself, which `messages` carries.

### `wait_for_task_update`

Follows a running task in the same conversation. It waits for new messages, a changed result, or completion. You get the outcome without checking status by hand. It's read-only, and your editor can auto-approve it.

| Argument           | Required | Description                                                                                                 |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `trigger_event_id` | Yes      | The task to follow.                                                                                         |
| `cursor`           | No       | Omit for an immediate initial snapshot. Reuse the `cursor` a prior call returned to receive later messages. |
| `wait_seconds`     | No       | How long one wait lasts, from 0 to a server maximum of 30 seconds. Defaults to 30 when omitted.             |

Each call returns a page of new conversation messages in `messages`, plus a `cursor` to pass to the next call. Each `messages` entry has the same shape as the ones `get_task_status` returns, with a stable `id`, a `sequence`, an `author`, and the message text. Reads never consume messages. Retrying the same call with the same `cursor` is safe. It may repeat messages your editor already saw, which your editor dedupes by `id`. A `has_more_messages` flag is true when more pages are ready. The `update_type` is `snapshot` on the first call for a cursor, which is when you omit `cursor`. It's `changed` when new messages or a new result arrived, and `timeout` when nothing changed during the wait. The `result` and `finished` fields report the task's outcome and whether it has finished. The `result` mirrors the outcome payload `get_task_status` returns. It carries the task's `resolution` note and its `suggestions`, each with its docs pull request link and review status. Every call also returns a `next_call`, which names `wait_for_task_update` and its arguments.

Follow `next_call` until it's null. `next_call` stays set while `has_more_messages` is true or the task isn't finished. It becomes null only once the task is `finished` and `has_more_messages` is false. Your editor never stops on `finished` alone, so it never drops a trailing message page. A `timeout` is normal: your editor keeps waiting through the next `next_call` without a separate sleep and without narrating unchanged state. Waiting doesn't cancel the cloud work.

You stay in control of following. Ask your editor to follow just once, or to stop at any time. `get_task_status` stays available to check a long-running task on demand.

### `send_task_message`

Use `send_task_message` to add an instruction to a task that's still running. Use `submit_documentation_task` to start a new task, and `request_changes` to revise a suggestion Promptless already produced.

Sends an additional instruction into a task that's already running. The instruction folds into that running task's work, and no new task starts. A task stops accepting messages once it finishes, including one that finished by reporting a blocker or by marking a clarifying question. To answer a clarifying question, use [`answer_task_question`](#answer-a-clarifying-question) instead; it answers a finished task's marked question.

| Argument           | Required | Description                                                                                                                                                                  |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trigger_event_id` | Yes      | The original task's ID (the one returned at submission). Reusing it keeps the reply on the same task; it does not create another task.                                       |
| `message`          | Yes      | The instruction to add. Up to 20,000 characters after trimming.                                                                                                              |
| `idempotency_key`  | No       | A safe-retry key. Retrying with the same key and the same text returns the original message marked deduplicated. The same key with different text is rejected as a conflict. |

It returns the stored `message` plus a `deduplicated` boolean. When the message is newly stored, `deduplicated` is `false`; it comes back `true` only when an `idempotency_key` retry matches an already-stored message. That stored `message` has the same shape as an entry in `get_task_status`'s `messages` array.

Like reading a task's status, sending isn't limited to tasks you started. You can send to an eligible task in your organization by its `trigger_event_id`. Task conversations apply to tasks submitted over the API or MCP, and to tasks created by calling `request_changes` over MCP. Reading a task's status with `get_task_status` stays available for every task source.

Like the other work-changing tools, it prompts before it runs and isn't auto-approved.

### `answer_task_question`

Use `answer_task_question` to answer a clarifying question a finished task marked. Use `send_task_message` to add an instruction to a task that's still running. For the full walkthrough, see [Answer a clarifying question](#answer-a-clarifying-question).

Answers the one clarifying question a finished task marked, so Promptless continues the work.

| Argument              | Required | Description                                                                                                                                      |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `trigger_event_id`    | Yes      | The finished task whose question you're answering (UUID).                                                                                        |
| `question_message_id` | Yes      | The marked question's message ID (UUID).                                                                                                         |
| `answer`              | No       | The answer text, 1–8000 characters. Omit it to have your editor open its native input form. Supply it only when you've already given the answer. |

It returns the `question` text, an `outcome`, an optional continuation `trigger_event_id`, an optional `next_call`, and a `message`. The `outcome` is one of five values:

- `submitted`. The answer is accepted, and Promptless starts a new continuation task. That continuation carries the original request, context, clarification history, and links to any results. `next_call` and `trigger_event_id` point at it, so follow `next_call`.
- `already_answered`. The question already had an answer committed, by an earlier call or an overlapping native form. Retrying with the same answer returns that committed answer instead of erroring. If a different answer won first, yours isn't submitted. Follow the task the returned `trigger_event_id` names, which points at the continuation already created.
- `unavailable`. Your editor can't show a native form, so it asks the question in chat and calls `answer_task_question` again with the answer.
- `decline` or `cancel`. You declined or canceled the question, so following stops.

Like the other work-changing tools, it prompts before it runs and isn't auto-approved.

### `request_changes`

Use `request_changes` when you want Promptless to make the change for you. Use `update_suggestion` to set the suggestion's labels, assignees, or title, or to open its pull request yourself. Use `close_suggestion` to end a review without shipping it.

Asks Promptless to revise a suggestion it already produced. This is the revision loop.

| Argument        | Required | Description                                                                          |
| --------------- | -------- | ------------------------------------------------------------------------------------ |
| `suggestion_id` | Yes      | The ID of the suggestion to change (from `search_suggestions` or `get_task_status`). |
| `instructions`  | Yes      | What to change about the suggestion.                                                 |

Promptless updates that suggestion's existing docs pull request instead of opening a second one. It returns a task ID you check with `get_task_status`, plus a `next_call` that follows the revision task with `wait_for_task_update`. If the suggestion's pull request is no longer one Promptless can revise, the tool reports that back; start a new task with `submit_documentation_task` instead.

### `update_suggestion`

Sets a suggestion's metadata (its labels, assignees, and title) yourself, and optionally opens its docs pull request. This is the path where you make the change yourself. By contrast, `request_changes` has Promptless make it, and `close_suggestion` ends a review without shipping it. Pass the suggestion's ID (from `search_suggestions` or `get_task_status`).

| Argument            | Required | Description                                                                                                                          |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `suggestion_id`     | Yes      | The suggestion to update.                                                                                                            |
| `labels`            | No       | Replaces the suggestion's stored labels. Omit to leave them alone; pass an empty list to clear them.                                 |
| `assignees`         | No       | Replaces the suggestion's stored assignees. Omit to leave them alone; pass an empty list to clear them.                              |
| `title`             | No       | Sets the suggestion's title.                                                                                                         |
| `open_pull_request` | No       | Pass `true` to open the suggestion's docs pull request in this call. Any `labels` or `assignees` edits in the same call apply first. |

The title can be set here, but a suggestion's description can't. Labels and assignees are applied before the title. The title edit is pushed to the host GitHub or GitLab pull request before it's stored. While a suggestion's pull request is open, the host owns its title. So a title edit has to reach the pull request to stick. If the suggestion has no open pull request yet, the title is stored directly, since there's no pull request to push to. If the host rejects the push, the call fails and the stored title is left unchanged. Any labels or assignees applied in the same call stay applied. The call is idempotent, so repeating it with the same arguments leaves the suggestion unchanged.

It returns the updated `labels`, `assignees`, and `title`. It also returns the docs pull request URL (`docs_pr_url`), which is null when the suggestion has no open pull request. Finally, it reports whether this call opened the pull request (`pull_request_opened`).

Because `labels` and `assignees` each replace the stored list, adding one without dropping the others means sending the full desired list. Read the current values first with `search_suggestions`, which returns each suggestion's `labels` and `assignees`. Setting them tags this one suggestion; it isn't a standing rule that auto-assigns or auto-labels future suggestions.

Opening the pull request is idempotent too. If the suggestion's docs pull request is already open, setting `open_pull_request` to `true` returns the existing pull request. It then reports `pull_request_opened` as false rather than opening a second one.

### `close_suggestion`

Ends a review without shipping it. This is the close path. It contrasts with revising the suggestion using `request_changes`, or opening its pull request yourself with `update_suggestion`.

| Argument        | Required | Description                            |
| --------------- | -------- | -------------------------------------- |
| `suggestion_id` | Yes      | The suggestion to close.               |
| `reason`        | No       | An optional note saved with the close. |

Closing the suggestion closes its docs pull request on the host first. If the host refuses to close the pull request, the suggestion stays open and the call reports why. A pull request that already merged, or otherwise shipped, can't be closed. If the suggestion has no open pull request, the suggestion closes normally.

Closing can't be undone from your editor: no MCP tool reopens a closed suggestion. To pursue the change again, start a new task with `submit_documentation_task`.

The close is attributed to your MCP client, so it's distinguishable from a close done in the dashboard. It also records who closed it: you, plus your editor's registered client name. Any `reason` you pass is saved with the close.

In the dashboard's close dialog, the **Send to Promptless** option sends your closing comment to Promptless and starts a follow-up run. `close_suggestion` has no equivalent, so a close over MCP starts no follow-up task.

The call returns the `suggestion_id`, the resulting `status`, and a `message`. Like the other work-changing tools, it prompts before it runs. It's destructive and can't be auto-approved.

### `list_recent_tasks`

Lists your organization's recent documentation tasks, newest first, each with the `trigger_event_id` you pass to `get_task_status`. Use it when you've lost a task's ID, or to see what Promptless has been working on. Like `get_task_status`, it covers tasks started from Slack, a GitHub pull request, or the dashboard, as well as tasks submitted over MCP. A task submitted over the API is read by ID with `get_task_status`.

### `search_suggestions`

Searches your existing suggestions by keyword and status. Use it to check whether a change is already covered before starting a new task, or to find a suggestion to revise.

| Argument | Required | Description                                                                                                                                                                                                                                                                                                                                                                                  |
| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`  | Yes      | Matches a suggestion's title and description. Must be at least 3 characters after trimming.                                                                                                                                                                                                                                                                                                  |
| `status` | No       | Restricts results to one of `draft`, `open`, `merged`, or `closed`.                                                                                                                                                                                                                                                                                                                          |
| `labels` | No       | A list of label strings. Returns only suggestions carrying at least one of the given labels. This is an any-of match. Omit it or pass an empty list to apply no label filter, so results come back across all labels. Matches exactly, including case, so a label in the wrong case returns nothing; call `search_suggestions` without `labels` first to see the exact stored label strings. |
| `limit`  | No       | Caps how many results come back. Defaults to 25, never exceeds 100.                                                                                                                                                                                                                                                                                                                          |

When more suggestions match than were returned, the result sets a `truncated` flag so you know to narrow the query. Filtering by `labels` pulls a labeled queue, such as every `P0` suggestion, in one call. That saves you fetching everything and filtering client-side, and the `triage-suggestions` workflow skill below relies on it. A `draft` or `open` suggestion is still live; a `merged` or `closed` one is already resolved. Each result also carries its `labels` and `assignees`, each a list of strings, and its `branch_name` (the git branch in the documentation repository the suggestion targets, always present). Use them to pick the suggestion to hand to `update_suggestion` or `request_changes`. You can also check out and diff the proposed change locally, even before its docs pull request opens. Once the suggestion's pull request has merged or closed, the branch may no longer exist, since hosts often delete it. So a local checkout applies to a still-open suggestion.

## Read and edit documentation directly

These six tools are available only at `https://api.gopromptless.ai/mcp/with-direct-edits`. With them, your client finds pages, edits them on an open suggestion's branch, checks the diff, and opens the pull request with `update_suggestion`.

Edits go on an open suggestion. For a change no open suggestion covers, start a task with `submit_documentation_task`, then edit the suggestion it creates.

Your client can auto-approve the four read tools: `list_documentation_files`, `read_documentation_file`, `search_documentation`, and `get_suggestion_diff`. The two write tools, `write_documentation_file` and `edit_documentation_file`, ask before each run.

### Choose what a read covers

`list_documentation_files`, `read_documentation_file`, and `search_documentation` take the same two optional arguments to choose what they read:

| Argument            | Required | Description                                                                                                                                          |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `doc_collection_id` | No       | The collection to read, from `list_doc_collections`. Pass it when your organization has more than one collection and you don't pass `suggestion_id`. |
| `suggestion_id`     | No       | The suggestion whose branch to read, to see pages as it proposes them. Omit it to read the collection's default branch, your published docs.         |

Each read returns a `ref` with the `sha` and `branch_name` it read. Pass that `sha` as `expected_head_sha` when you edit. Reads cover only the paths Promptless maintains for the collection.

### `list_documentation_files`

Lists a collection's file paths in sorted order. Use it to find a page's path before you read or edit it.

| Argument      | Required | Description                                                        |
| ------------- | -------- | ------------------------------------------------------------------ |
| `path_prefix` | No       | Lists only paths that start with this prefix, such as `docs/api/`. |
| `limit`       | No       | How many paths to return. Defaults to 500, never exceeds 2,000.    |

It returns the `files`, a `total` count of matching paths, and a `truncated` flag. When `truncated` is true, narrow the listing with `path_prefix`.

### `read_documentation_file`

Reads one text file by its repository-relative `path`, which is required. It returns the file's `content` and `size_bytes`. It refuses binary files and files over 256 KB.

### `search_documentation`

Finds lines that match text or a regular expression across a collection's text files, such as Markdown, MDX, reStructuredText, YAML, JSON, and HTML.

| Argument         | Required | Description                                                                           |
| ---------------- | -------- | ------------------------------------------------------------------------------------- |
| `query`          | Yes      | The text to find, or a regular expression when `regex` is true. Up to 256 characters. |
| `regex`          | No       | Pass `true` to treat `query` as an RE2 regular expression, similar to `grep -E`.      |
| `case_sensitive` | No       | Pass `true` to match case exactly.                                                    |
| `path_prefix`    | No       | Searches only files whose path starts with this prefix.                               |
| `limit`          | No       | How many matching lines to return. Defaults to 50, never exceeds 200.                 |

RE2 syntax covers character classes, alternation, and repetition, such as `retr(y|ies)` or `v[0-9]+\.[0-9]+`. It doesn't support backreferences such as `\1` or lookaround such as `(?=...)`.

Each match returns the file `path`, `line` number, and line `text`. A search reads up to 400 files of up to 128 KB each, within 10 seconds. `files_skipped` counts the files it didn't reach; when it's above zero, search again with a narrower `path_prefix`. `truncated` is true when more lines matched than `limit` returned.

### `get_suggestion_diff`

Shows what a suggestion changes. Pass its `suggestion_id`, which is required. It returns one unified diff per changed file against the collection's base branch, and each file's `status`: `added`, `modified`, `removed`, or `renamed`. It also returns the suggestion's `head_sha`, which you can pass as `expected_head_sha` when you edit.

Diff text is capped at 200,000 characters per response. Once the cap is reached, each later file carries a `diff` of `null` and `truncated` is true. Binary files carry no diff text.

### `write_documentation_file`

Creates or replaces one file on an open suggestion's branch with the full content you pass. Use it for a new page or a rewrite of most of a page. For a change to part of a page, use `edit_documentation_file`.

| Argument            | Required | Description                                                                                                                                        |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `suggestion_id`     | Yes      | The open suggestion whose branch receives the commit.                                                                                              |
| `path`              | Yes      | The repository-relative file path, inside the paths Promptless maintains for the collection.                                                       |
| `content`           | Yes      | The complete new file content, up to 256 KB.                                                                                                       |
| `expected_head_sha` | No       | The `ref.sha` from your last read, or the `head_sha` from your last write. The write is refused when the suggestion's branch has moved since then. |

### `edit_documentation_file`

Replaces exact text in one file on an open suggestion's branch. It takes `suggestion_id`, `path`, and `expected_head_sha` as `write_documentation_file` does, plus `edits`, which is required.

`edits` is a list of 1 to 50 entries, each with an `old_text` and a `new_text`. Each `old_text` must match the file exactly once, so copy it verbatim from a read and include enough surrounding text to make it unique. An empty `new_text` deletes the matched text. The edits apply in order, and the call is refused when any `old_text` matches no place or several places.

### What a write commits

Each `write_documentation_file` or `edit_documentation_file` call makes one commit on the suggestion's branch, attributed to you and your client: `Update from <your email> via <client name>`. It returns the new `head_sha` to pass as `expected_head_sha` on your next write, plus the suggestion's `docs_pr_url` and `status`. When your edits leave the suggestion with no changes against its base branch, Promptless closes the suggestion and its docs pull request.

No tool deletes a file. To remove a page, describe the removal with `request_changes`.

## Answer a clarifying question

A task can finish by marking one clarifying question in your editor. This applies to a task you started over MCP. Answering it starts a new continuation task. That task carries the original request, the original context, the clarification history, and links to any results already produced. You pick up directly from the clarification.

To answer through the native form, you need an MCP client that negotiates a recent protocol version and declares an elicitation capability. That capability is the MCP feature that lets a server show an input form inside your editor.

A clarifying question reaches you through the same task-following loop this page documents. As your editor follows the task with `wait_for_task_update`, or as you check it with `get_task_status`, the response carries the marked `question` and a `next_call` pointing at `answer_task_question`. Your editor follows that `next_call` the same way it follows any other task.

How you answer depends on your MCP client:

- A client that declares an elicitation capability shows a native single free-text field titled **Your answer**, with the question as its prompt. The answer runs 1–8000 characters.
- A client without that capability receives `outcome: unavailable`. Your editor posts the question as a chat message. Reply in the same conversation, and your editor relays your answer by calling `answer_task_question` again.

Your editor follows the accepted answer via its `next_call`, which points at the new continuation task. The first committed answer wins. Answering the same question again returns `already_answered`, and a matching answer comes back unchanged. If a different answer won first, yours isn't submitted. You follow the task the response names, the continuation already created, to pick up the committed one. If you decline or cancel the question, no continuation is created and following stops. The original finished task and anything it already produced, such as suggestions, remain. To pursue the change, start a new task with `submit_documentation_task`.

## Workflow skills

If your editor supports it, Promptless can hand it step-by-step guidance for multi-step workflows that chain several of these tools together. A skill guides your editor through the [tools above](#available-tools) and adds no tools of its own. The editor decides when to load a skill, and you ask for what you want as usual.

Two skills ship today. `triage-suggestions` is available at both server URLs. `edit-documentation` is available only at the direct-edit URL.

`triage-suggestions` is a workflow for working through a backlog of suggestions. It pulls the backlog with `search_suggestions` and checks the `truncated` flag to see whether more are waiting. Then it reads each proposal in turn. Next it gives each suggestion one outcome, then hands the queue back to you. It can label or assign a suggestion with `update_suggestion`, send it back for a revision with `request_changes`, or close it with `close_suggestion`. Following that sequence keeps the editor from treating a truncated result set as your whole backlog. It also gives each suggestion exactly one outcome without you prompting each step.

`edit-documentation` walks your client through one direct edit. It finds the pages, picks or starts a suggestion, edits each page, checks the diff, and opens the pull request.

A skill doesn't change how the tools behave. The work-changing tools these skills call, such as `update_suggestion`, `request_changes`, `close_suggestion`, and `edit_documentation_file`, still prompt before each run, just as they do when you call them directly. A skill only guides the sequence; it doesn't bypass those confirmations.

  Skills reach your editor over the draft **Skills extension (SEP-2640)**. The MCP endpoint declares it as the `io.modelcontextprotocol/skills` capability in its `initialize` response. Many clients don't support the extension yet and show no skills. To check whether yours does, see its MCP settings or release notes. Because the extension is still a draft, its shape can change.

A client that doesn't support the extension, or ignores it, sees the same tools and calls them directly.

## Ask your editor

Ask in plain language. For example: "List my Promptless doc collections, then start a task to document the new authentication flow in the API docs collection." Your editor maps that to `list_doc_collections`, then `submit_documentation_task`. It follows the task automatically in the same conversation, using the `next_call` it gets back. It reports the outcome and docs pull request link back to you, without you checking status by hand.

To avoid duplicating work, search before you submit. Your editor runs `search_suggestions` first, and if nothing live comes back, submits the task. For example: "Before I ask Promptless to document the new webhook retries, search existing suggestions for 'webhook retries.'"

To check a task at a point in time, ask by its ID: "What's the status of Promptless task `<id>`?" Your editor calls `get_task_status` and reports the outcome and any docs pull request link. This is the on-request check, not the primary way you get an outcome. Reach for it for a task you didn't follow to completion, or to look in again later or from another session. It works for any task.

To read a task's conversation, ask for it: "What has Promptless said so far about task `<id>`?" Your editor calls `get_task_status` and reports the conversation.

To add to a task that's still running, tell Promptless what else to cover: "Tell Promptless task `<id>` to also cover the error responses." Your editor maps that to `send_task_message`, and the instruction folds into the running task. This works for tasks you started over the API or MCP, or created with `request_changes` over MCP. Check back with `get_task_status` to see the message added to the conversation.

A task can finish by marking one clarifying question. Answer it in plain language: "Answer Promptless task `<id>`'s clarifying question: yes, cover the deprecation notice." Your editor calls `answer_task_question`, and Promptless picks up your answer in a new task. Your editor follows that task via its `next_call`.

To change a suggestion Promptless already made, ask for a revision: "Revise Promptless suggestion `<id>` to also cover single sign-on." Your editor calls `request_changes`, and Promptless updates that suggestion's existing pull request instead of opening a new one. Your editor follows the revision task via `next_call` until it's done, the same way it follows a new task.

To set a suggestion's labels, assignees, or title, or open its docs pull request yourself, ask for that. For example: "Assign Promptless suggestion `<id>` to @alex, retitle it 'SSO setup,' and open its docs PR." Your editor calls `update_suggestion`, which applies the change and opens the pull request in the same step. To just retitle it without opening a pull request, leave that part out: "Retitle Promptless suggestion `<id>` to 'SSO setup.'"

To close a suggestion you won't ship, ask for that: "Close Promptless suggestion `<id>`. We decided not to document this." Your editor calls `close_suggestion` and saves your reason with the close; closing also closes the suggestion's docs pull request.

If you've lost track of a task's ID, ask for your recent ones: "What are my recent Promptless tasks?" Your editor calls `list_recent_tasks` and lists them newest first, so you can pick the ID to check.

To work through a backlog, ask for a triage pass: "Triage my open Promptless suggestions, label the P0s, and close anything we've decided against." If your editor supports [workflow skills](#workflow-skills), it can follow the `triage-suggestions` steps; if not, it calls the same tools directly. Either way the work-changing tools still prompt before they run, so you stay in control of what changes.

On the direct-edit URL, name the change and the suggestion to put it on: "Find the pages that say webhook retries default to 3. Change them to 5 on the open webhook retries suggestion, show me the diff, and open the PR." Each edit asks before it commits.

## See your MCP tasks in the dashboard

On the [Triggers page](https://app.gopromptless.ai/triggers), a task started over MCP shows an **MCP Task** pill with a byline reading `<client name> · submitted by @<username>`. Tasks submitted with an `sk-pl-` API key show an **API Task** pill.

To find MCP-originated suggestions on the [Suggestions list](https://app.gopromptless.ai/suggestions), set the **Trigger source** filter to "API". That filter includes both MCP and API-key submissions.

## Manage and revoke your connection

Connections re-authorize automatically. The connection you approve lasts 90 days. After that, automatic refresh stops, and you approve the connection in the browser again, the way you did at setup.

To revoke a connection, remove the `promptless` server from your editor, such as from Cursor's MCP settings. In Claude, remove the connector from **Customize** > **Connectors**. The dashboard's **Editor connection (MCP)** section shows setup instructions only, so revoke from your editor or chat app.

Promptless checks your organization membership on every call, and revokes the connection if you lose active membership. Each member manages their own connection. An admin can't revoke another member's connection for them.

## Troubleshooting

Tool failures come back as errors your editor's model sees, each formatted as `code: message`. Common ones:

- **Empty `instructions`**: resubmit with a specific `instructions` string.
- **A `doc_collection_id` that isn't a valid ID (UUID)**: call `list_doc_collections` and pass an `id` from the returned list.
- **An unrecognized `search_suggestions` status**: use one of `draft`, `open`, `merged`, or `closed`.
- **A missing `search_suggestions` `query`, or one shorter than 3 characters after trimming**: provide a `query` of at least 3 characters.
- **The organization hasn't finished setting up Promptless**: the tool returns "This organization has not finished setting up Promptless." Finish setup on the [Configuration page](https://app.gopromptless.ai/configuration), or ask a member with admin access to finish it.
- **A requested collection isn't configured**: the tool returns "The requested doc collection is not configured." Call `list_doc_collections` for a valid `id`, or configure the collection first.
- **A suggestion that can no longer be revised**: `request_changes` reports that the suggestion is no longer one Promptless can revise. Its pull request has moved beyond where a revision applies. Start a new task with `submit_documentation_task` instead.
- **An `update_suggestion` call that can't be applied**: a `suggestion_id` that isn't a valid ID (UUID) or matches no suggestion returns an error. Call `search_suggestions` for a valid ID. Setting a suggestion's labels, assignees, or title still succeeds even on a closed or merged suggestion. Only opening a pull request is refused for a closed suggestion that hasn't merged, and the tool reports why. If the host rejects the title push, the call fails and the stored title is left unchanged. Any labels or assignees from the same call stay applied. No MCP tool retracts a pull request while keeping the suggestion open for further editing. Closing over MCP with `close_suggestion` closes the suggestion and its pull request together. If you opened a pull request by mistake and want to keep working the suggestion, close the pull request on the host directly. The host is GitHub or GitLab.
- **A `close_suggestion` call that can't be applied**: a `suggestion_id` that isn't a valid ID (UUID) or matches no suggestion returns an error. Call `search_suggestions` for a valid ID. If the host refuses to close the pull request, the suggestion stays open and the tool reports why. A pull request that already merged can't be closed. A suggestion that's already closed can't be closed again, and the tool reports so.
- **Sending to a finished task**: the tool rejects it with `task_finished`. A task that finished by reporting a blocker or a clarification request has still finished, so it also rejects messages. Start a new task with `submit_documentation_task` to continue. If the finished task marked a clarifying question, answer it with [`answer_task_question`](#answer-a-clarifying-question). That continues the work in a new task.
- **Sending to a task that isn't API- or MCP-sourced**: the tool rejects it with `unsupported_task_source`. Task conversations are scoped to API and MCP submissions and to tasks created by calling `request_changes` over MCP. Read the task's status instead, or start an API or MCP task to converse.
- **An empty or over-length message**: the tool rejects it with `invalid_message`. The limit is 20,000 characters after trimming.
- **A retried message that conflicts with a stored one**: the tool rejects it with `idempotency_conflict`. The retry reused the same `idempotency_key` with different text. Resend with a new `idempotency_key`, or with the original text.
- **A `wait_for_task_update` cursor that's invalid or from another task**: the tool rejects it with `invalid_cursor`. Omit the cursor to read from the beginning. If task storage doesn't respond in time, the tool returns `task_read_timeout`; retry the same task and cursor. Set `wait_seconds` between 0 and 30, the server maximum.
- **`answer_task_question` returns `unavailable`**: your editor can't show a native form. It asks the clarifying question in chat and calls `answer_task_question` again with your answer.
- **`answer_task_question` returns `already_answered`**: the question already had an answer committed. Follow the task the returned `trigger_event_id` names, which is the continuation already created. If a different answer won first, yours wasn't submitted; following that task shows the committed answer.
- **`answer_task_question` returns `decline` or `cancel`**: you declined or canceled the question. No work continues and following stops. The original task and anything it already produced remain. To pursue the change, start a new task with `submit_documentation_task`.
- **An answer reference that points at an unrelated task**: `answer_task_question` rejects it with `continuation_conflict`. This happens when the `idempotency_key` matches a task other than this question's own continuation. That covers a different parent task, a different question, or a task ineligible for a clarifying answer. Promptless doesn't reuse that task. Start a new task with `submit_documentation_task`, restating your original request and your answer.
- **A deduplicated answer whose continuation can't be found**: `answer_task_question` rejects it with `continuation_unavailable`. This case is transient. A concurrent identical answer to the same question was still committing its continuation when this call looked for it. Retry `answer_task_question` with the same arguments.
- **A read that names no collection in an organization with several**: the tool reports the available collections. Pass a `doc_collection_id` from that list, or pass a `suggestion_id`, which selects its collection.
- **A path outside the paths Promptless maintains**: the read, list, or write is refused. Promptless reads and edits only the paths configured for the collection. Call `list_documentation_files` for valid paths.
- **A `search_documentation` query that isn't valid RE2**: the tool reports that the query is not a valid RE2 regular expression. The error names what failed to parse. Rewrite the pattern without backreferences or lookaround, or set `regex` to `false` to search for the literal text.
- **A `search_documentation` query over 256 characters**: the tool refuses it. Shorten the query.
- **A file over 256 KB**: `read_documentation_file` and both write tools refuse it. A binary file is refused for reading too.
- **A write to a closed suggestion**: the tool refuses it, since a closed suggestion's branch accepts no edits. Pick an open suggestion with `search_suggestions`, or start a task with `submit_documentation_task`.
- **A write to a suggestion whose task hasn't finished**: the tool refuses it until Promptless records the suggestion's first commit. Wait for the task to finish, then retry.
- **`stale_head`**: the suggestion's branch changed after your last read, so `expected_head_sha` no longer matches it. The error names the current commit. Read the file again and retry with that commit as `expected_head_sha`.
- **An `old_text` that matches no place or several places**: `edit_documentation_file` refuses the whole call and reports which edit failed and how many places it matched. Read the file again, copy the text verbatim, and include enough surrounding text to match once.
- **Denied, canceled, or expired consent**: re-run the authorize step. In Claude Code, run `/mcp` and pick **promptless** again. In Cursor, click **Needs login** again.

### Setup issues

First-run snags usually clear with a retry:

- **The browser consent tab doesn't open**: re-run the authorize step. In Claude Code, run `/mcp` and pick **promptless**; in Cursor, click **Needs login**.
- **No promptless entry under `/mcp` in Claude Code**: confirm the add command ran, then re-open the client.
- **Cursor's Needs login button doesn't respond**: remove the server and add it again.

## See also

- [API triggers](https://promptless.ai/docs/for-docs/connect/triggers/api), for server-to-server and CI callers that use an API key
- [Use Promptless from Claude.ai or ChatGPT](https://promptless.ai/docs/for-docs/work-the-queue/claude-and-chatgpt), to connect from a web chat app
- [Access and permissions](https://promptless.ai/docs/for-docs/security/access-and-permissions), for organization roles and what members can do
- [Noise and relevance filtering](https://promptless.ai/docs/for-docs/tune/noise-and-relevance-filtering), to control which submitted tasks produce suggestions