Skip to content

For the complete documentation index, see llms.txt.

MCP triggers

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

To use Promptless from the Claude.ai or ChatGPT web app, follow Use Promptless from Claude.ai or ChatGPT.

  • 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 finished.
  • An active membership in the organization. MCP needs no API key and no particular organization role.

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 tools so your client can edit doc files itself. 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:

Terminal window
claude mcp add --transport http promptless https://api.gopromptless.ai/mcp

The same URL and command also appear in the dashboard under Settings, in the Editor connection (MCP) section, which every organization member can see.

  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.

  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:

    {
    "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 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.

  1. Add the promptless server with the code CLI:

    Terminal window
    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.

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

    Terminal window
    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.

Add Promptless to Claude as a custom connector:

  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.

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.

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

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.

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.

Both server URLs carry these tools, which let you check on your collections, tasks, and suggestions, or queue and change your documentation work. The direct-edit URL adds more, described in Read and edit documentation directly. These 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. These 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.

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.

ArgumentRequiredDescription
instructionsYesWhat you want documented.
doc_collection_idNoTarget one collection. Omit to route across all your collections.
contextNoOptional metadata attached to the request; appears in trigger history.
attachmentsNoLinks 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 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.

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

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, MCP, or the dashboard’s New Task page. 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, MCP, or the dashboard’s New Task page. It’s also populated 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 ids 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.

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.

ArgumentRequiredDescription
trigger_event_idYesThe task to follow.
cursorNoOmit for an immediate initial snapshot. Reuse the cursor a prior call returned to receive later messages.
wait_secondsNoHow 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.

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 instead; it answers a finished task’s marked question.

ArgumentRequiredDescription
trigger_event_idYesThe original task’s ID (the one returned at submission). Reusing it keeps the reply on the same task; it does not create another task.
messageYesThe instruction to add. Up to 20,000 characters after trimming.
idempotency_keyNoA 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, MCP, or the dashboard’s New Task page, 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.

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.

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

ArgumentRequiredDescription
trigger_event_idYesThe finished task whose question you’re answering (UUID).
question_message_idYesThe marked question’s message ID (UUID).
answerNoThe 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.

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.

ArgumentRequiredDescription
suggestion_idYesThe ID of the suggestion to change (from search_suggestions or get_task_status).
instructionsYesWhat 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.

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

ArgumentRequiredDescription
suggestion_idYesThe suggestion to update.
labelsNoReplaces the suggestion’s stored labels. Omit to leave them alone; pass an empty list to clear them.
assigneesNoReplaces the suggestion’s stored assignees. Omit to leave them alone; pass an empty list to clear them.
titleNoSets the suggestion’s title.
open_pull_requestNoPass 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.

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.

ArgumentRequiredDescription
suggestion_idYesThe suggestion to close.
reasonNoAn 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.

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.

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.

ArgumentRequiredDescription
queryYesMatches a suggestion’s title and description. Must be at least 3 characters after trimming.
statusNoRestricts results to one of draft, open, merged, or closed.
labelsNoA 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.
limitNoCaps 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.

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

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

ArgumentRequiredDescription
doc_collection_idNoThe 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_idNoThe 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.

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

ArgumentRequiredDescription
path_prefixNoLists only paths that start with this prefix, such as docs/api/.
limitNoHow 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.

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.

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

ArgumentRequiredDescription
queryYesThe text to find, or a regular expression when regex is true. Up to 256 characters.
regexNoPass true to treat query as an RE2 regular expression, similar to grep -E.
case_sensitiveNoPass true to match case exactly.
path_prefixNoSearches only files whose path starts with this prefix.
limitNoHow 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.

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.

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.

ArgumentRequiredDescription
suggestion_idYesThe open suggestion whose branch receives the commit.
pathYesThe repository-relative file path, inside the paths Promptless maintains for the collection.
contentYesThe complete new file content, up to 256 KB.
expected_head_shaNoThe 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.

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.

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.

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.

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 and adds no tools of its own. The editor decides when to load a skill, and you ask for what you want as usual.

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.

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

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, tasks you created with request_changes over MCP, and New Tasks submitted from the dashboard. 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, 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.

On the Triggers page, 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, set the Trigger source filter to “API”. That filter includes both MCP and API-key submissions.

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.

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, 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. That continues the work in a new task.
  • Sending to a task whose source has no conversation: the tool rejects it with unsupported_task_source. Task conversations cover API and MCP submissions, tasks created by calling request_changes over MCP, and New Tasks submitted from the dashboard. Read the task’s status instead, or submit a New Task or 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.

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.