Prompts
A prompt is a reusable, named message template your agent can fetch over MCP. Instead of hard-coding instructions into every client, you publish a prompt once and every agent that can reach it can pull the same template by name.
How an MCP client consumes prompts
apistash advertises the prompts capability, so a connected client can:
prompts/list— discover the prompts available to the current credential.prompts/get— fetch a prompt by name, with any declared arguments filled in.
The list is computed per credential on every request — you only ever see the prompts you are allowed to use. It combines your accessible customer prompts with available platform prompts. Both need the effective Prompts capability.
For customer prompts, the server emits prompts/list_changed when a credential's visible list can change: when a prompt appears or disappears, or when its listed name, description, or argument declaration changes. Editing only the prompt content or version-retention policy does not change prompts/list and does not emit this notification. Notifications are sent to sessions that may be affected. Clients then re-run prompts/list, whose result remains permission-filtered.
Platform prompts
Platform prompts are provided and maintained by apistash, separately from your customer content. They have names starting with apistash/, consume no customer prompt slots, and cannot be edited through customer management tools or the dashboard. Governed platform prompts require the effective Prompts capability, selection in the personal or organization platform-prompt allowlist under MCP Settings, and admission by the key or team Prompt policy. Prompt policies select platform and customer prompts together; the two catalogs retain separate IDs. Organization-wide platform prompts must also be allowlisted and are admitted alongside additive team policies.
apistash/agent-doctor asks your connected model to audit the active Agent definitions delivered to its credential for inconsistencies, overlapping responsibilities, and handoff problems. It returns instructions for a read-only audit; apistash does not run a model or enforce the model's obedience to those instructions. See Audit Agent definitions for selection, access requirements, and the report.
The guaranteed name is the MCP name apistash/agent-doctor. A client may expose it as a slash command, for example /apistash/agent-doctor, or use a different spelling or prompt picker. Consult your client's prompt interface.
In MCP Settings, both platform catalogs support search, category filters and paginated selection. Agent Doctor is in the management category. You can select or clear the current page or every matching result; your selections remain in the draft when you change filters or pages, until you save or discard them. Categories help you configure access in the dashboard; they are not additional fields in the native MCP prompt response.
Platform allowlist and Prompt policy changes notify affected sessions. Platform catalog updates do not emit prompts/list_changed. Refresh your client's prompt list to see updates; a session connected to an older server version may need to reconnect after a release.
Errors
The native prompt methods have no tool-result error channel, so a failure surfaces as a JSON-RPC protocol error. Anything your client can act on — a missing required argument, a credential without the prompts capability — is an invalid_params error carrying a precise, stable code (for example missing_required_argument) in its data, so you can branch on the code instead of parsing the message. A customer prompt outside your visible set fails as method_not_found, indistinguishable from one that doesn't exist. Unknown or deprecated platform prompts also return method_not_found. A known platform prompt denied by its allowlist or policy returns prompt_not_permitted; a missing capability returns capability_denied. Listings omit governed prompts when their capability or policy denies access.
The prompt management tools are ordinary tools and follow the tool error model instead, returning failures as isError tool results.
Arguments
A prompt can declare arguments — named parameters a client fills in when it fetches the prompt. Give each argument a name, an optional description, and whether it is required, then reference it in the content with double braces:
Summarize the following
{{language}}code for a{{audience}}reader.
When a client calls prompts/get it supplies values, and the server returns the content with each {{name}} replaced. Fetching the prompt above with language = "Rust" and audience = "a beginner" returns:
Summarize the following Rust code for a beginner reader.
The rules:
- Content and arguments must match. Every
{{name}}you write must be a declared argument, and every declared argument must be referenced at least once — a prompt that leaves an argument unused, or references one that isn't declared, is rejected when you save it. This keeps a prompt self-consistent: no parameter a client is asked for that the text never uses, and no{{name}}that would come back unfilled. - Only identifier-shaped braces are placeholders. A brace sequence that isn't a simple name — a JSON example like
{"ok": true}, or{{ not a name }}— isn't a placeholder and is left untouched, so you can write prose and code freely. Surrounding spaces are ignored, so{{ language }}works too. - A required argument with no value is rejected; an optional one that is left out becomes empty.
Arguments are advertised on prompts/list so a client knows what to ask for. For customer prompts, they travel with the content: editing a prompt's arguments records a new version, and restoring an older version brings back the arguments it had.
Substitution happens when a client uses a prompt (prompts/get). When an agent instead reads a customer prompt to inspect or copy it — via the get_prompt management tool — it gets the raw template with the {{name}} placeholders intact, not a filled-in copy.
Versioning
Every customer prompt keeps a history of versions; the latest version is the active one served by prompts/get. Updating a prompt records a new version. Each plan limits how many versions a prompt keeps, and when you reach that limit you choose whether a new version is rejected or the oldest one is dropped.
Names and ownership
Customer prompts belong to an owner — you, a team, or an organization. On the MCP surface, names are prefixed by ownership space so that identically-named prompts never shadow each other:
| Owner | Name on MCP |
|---|---|
| Your personal-in-org prompts | me/{name} |
| Team-owned prompts | {team}/{name} |
| Organization catalogue | {name} (unprefixed) |
Where prompts come from
You can create and manage customer prompts three ways: in the dashboard, through the REST API, or by letting an agent do it over MCP with the management tools (list_prompts, get_prompt, create_prompt, update_prompt, delete_prompt). A standalone personal credential uses bare names; an organization-scoped credential uses me/name for the represented member's private prompts and <team>/name for a bound team. Bare organization-scoped names read from the organization catalogue, whose publication stays a deliberate dashboard action.
Which customer prompts a credential can reach is governed by the access model, and for personal API keys you can narrow it down further — see Authentication.
The published prompts require effective prompts capability and admission through the access model. Platform prompts additionally use their platform allowlist; customer prompts use their ownership space.