Skip to content
Back to Docs
MCP Reference

MCP Tools Reference

The PromptOT MCP server exposes 23 tools across five areas: prompts, blocks, variables, versions, and test cases. Every tool requires one or more scopes — see the scopes reference for the full vocabulary.

For maintainers: if you add or remove a tool in apps/mcp/src/tools/*.ts, update this page too. A future task is to extract a shared TOOL_CATALOG constant so the docs never drift.

Prompts

6 tools

List, fetch, create, update, and delete prompts in a project.

list_prompts
prompts:read

List all prompts in the project.

Inputs

limitnumber
Optional cap on the number of prompts returned.
get_prompt
prompts:read

Fetch a single prompt with blocks, variables, and compiled output.

Inputs

prompt_idstringrequired
The prompt's UUID.
truncateboolean
Truncate the compiled output to fit max_tokens (default: true).
max_tokensnumber
Max tokens to return when truncate is enabled (default: 2000).
get_compiled_prompt
prompts:read

Compile a prompt to markdown and return the assembled string.

Inputs

prompt_idstringrequired
The prompt's UUID.
truncateboolean
Truncate the compiled output (default: true).
max_tokensnumber
Max tokens to return (default: 2000).
create_prompt
prompts:write

Create a new prompt with default blocks.

Inputs

namestringrequired
Display name of the prompt.
descriptionstring
Short description shown in lists.
tagsstring[]
Tags to attach for filtering.
folder_idstring
Folder UUID to nest the prompt under.
update_prompt
prompts:write

Update prompt metadata (name, description, tags, folder).

Inputs

prompt_idstringrequired
The prompt's UUID.
namestring
New display name.
descriptionstring
New description.
tagsstring[]
Replacement tag set.
folder_idstring
New folder UUID, or null to move to root.
delete_prompt
prompts:delete

Permanently delete a prompt.

Inputs

prompt_idstringrequired
The prompt's UUID.
confirmtruerequired
Must be literal true to guard against accidental deletes.

Blocks

5 tools

Manage typed blocks (role, context, instructions, guardrails, output_format, custom).

list_blocks
blocks:read

List all blocks for a prompt in sort order.

Inputs

prompt_idstringrequired
The prompt's UUID.
create_block
blocks:write

Create a new block on a prompt.

Inputs

prompt_idstringrequired
The prompt's UUID.
type'role' | 'context' | 'instructions' | 'guardrails' | 'output_format' | 'custom'required
Block type — determines compilation order and styling.
titlestringrequired
Section heading rendered as ## Title.
contentstring
Markdown body of the block. Supports {{variable}} interpolation.
sort_ordernumber
Position in the block list. Defaults to end of list.
enabledboolean
Whether the block participates in compilation (default: true).
is_requiredboolean
Marks the block as required for validation purposes.
update_block
blocks:write

Update block fields.

Inputs

block_idstringrequired
The block's UUID.
titlestring
New section heading.
contentstring
New markdown body.
enabledboolean
Toggle compilation participation.
sort_ordernumber
New position in the block list.
delete_block
blocks:write

Permanently delete a block from a prompt.

Inputs

block_idstringrequired
The block's UUID.
reorder_blocks
blocks:write

Reorder all blocks on a prompt in one atomic call.

Inputs

prompt_idstringrequired
The prompt's UUID.
block_idsstring[]required
Block UUIDs in the desired final order.

Variables

3 tools

Manage {{variable}} placeholders that are resolved at fetch time.

list_variables
variables:read

List all variables defined on a prompt.

Inputs

prompt_idstringrequired
The prompt's UUID.
upsert_variable
variables:write

Create or update a variable on a prompt.

Inputs

prompt_idstringrequired
The prompt's UUID.
keystringrequired
Variable name. Must match ^[a-zA-Z_][a-zA-Z0-9_]*$.
default_valuestring
Fallback used when no value is passed at fetch time.
descriptionstring
Human-readable description for teammates and the dashboard.
delete_variable
variables:write

Delete a variable from a prompt.

Inputs

variable_idstringrequired
The variable's UUID.

Versions

5 tools

Save drafts, publish immutable versions, roll back, and diff.

list_versions
versions:read

List all versions (drafts and published) for a prompt.

Inputs

prompt_idstringrequired
The prompt's UUID.
save_draft_version
versions:write

Snapshot the current block/variable state as a new draft version.

Inputs

prompt_idstringrequired
The prompt's UUID.
changelog_notestring
Optional note describing what changed in this draft.
publish_version
versions:publish

Promote a draft version to published. Production API keys will start returning this version.

Inputs

version_idstringrequired
The version's UUID.
changelog_notestring
Optional note attached to the publish event.

Fires the prompt.published webhook to all registered webhook endpoints for the project.

rollback_to_version
versions:write

Restore the version's blocks/variables as a new draft on the same prompt.

Inputs

version_idstringrequired
The version to restore from.
diff_versions
versions:read

Compare two versions and return a structured diff of blocks and variables.

Inputs

version_a_idstringrequired
The base version's UUID.
version_b_idstringrequired
The target version's UUID.

Test Cases

4 tools

Manage reusable test inputs for evaluation runs.

list_test_cases
test_cases:read

List all test cases attached to a prompt.

Inputs

prompt_idstringrequired
The prompt's UUID.
create_test_case
test_cases:write

Create a new test case for a prompt.

Inputs

prompt_idstringrequired
The prompt's UUID.
namestringrequired
Display name of the test case.
input_textstringrequired
User input to feed the prompt during evaluation.
variable_overridesRecord<string, string>
Per-test variable values that override defaults.
expected_outputstring
Reference output for grading.
evaluation_criteriaobject
Grader config (contains, regex_match, similarity_score, etc.).
update_test_case
test_cases:write

Update fields on an existing test case.

Inputs

test_case_idstringrequired
The test case's UUID.
namestring
New display name.
input_textstring
New user input.
variable_overridesRecord<string, string>
New override map.
expected_outputstring
New reference output.
evaluation_criteriaobject
New grader config.
delete_test_case
test_cases:write

Delete a test case permanently.

Inputs

test_case_idstringrequired
The test case's UUID.