MCP overview
MCP Reference

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.

Usage Examples

Realistic prompts you can send to Claude with the PromptOT MCP connector enabled. Claude selects the right tools automatically.

Build a customer support prompt

User prompt

“Create a prompt called 'Customer Support Agent' with a role block that says 'You are a helpful customer support agent for an e-commerce platform', an instructions block with guidelines for handling refunds and shipping issues, and a guardrails block that prevents sharing internal pricing data.”

Claude calls create_prompt, then create_block three times (role, instructions, guardrails) to build a structured multi-block prompt ready for delivery via the API.

create_promptcreate_block

Version and publish a prompt

User prompt

“List my prompts, save a draft of the 'Onboarding Email Writer' prompt, and then publish it so production API keys start returning the new version.”

Claude calls list_prompts to find the prompt, save_draft_version to snapshot the current state, then publish_version to promote it. Production API consumers immediately get the updated prompt.

list_promptssave_draft_versionpublish_version

Add test cases for evaluation

User prompt

“Add three test cases to my 'SQL Query Generator' prompt: one for a simple SELECT, one for a JOIN query, and one edge case with an empty table name. Include expected outputs so I can evaluate quality.”

Claude calls create_test_case three times with different input_text and expected_output values. These test cases can then be used in evaluation runs to measure prompt quality across scenarios.

create_test_case

Prompts

6 tools

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

list_promptsprompts:read

List all prompts in the project.

Inputs
limitnumberOptional cap on the number of prompts returned.
get_promptprompts:read

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

Inputs
prompt_idstringrequiredThe prompt's UUID.
truncatebooleanTruncate the compiled output to fit max_tokens (default: true).
max_tokensnumberMax tokens to return when truncate is enabled (default: 2000).
get_compiled_promptprompts:read

Compile a prompt to markdown and return the assembled string.

Inputs
prompt_idstringrequiredThe prompt's UUID.
truncatebooleanTruncate the compiled output (default: true).
max_tokensnumberMax tokens to return (default: 2000).
create_promptprompts:write

Create a new prompt with default blocks.

Inputs
namestringrequiredDisplay name of the prompt.
descriptionstringShort description shown in lists.
tagsstring[]Tags to attach for filtering.
folder_idstringFolder UUID to nest the prompt under.
update_promptprompts:write

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

Inputs
prompt_idstringrequiredThe prompt's UUID.
namestringNew display name.
descriptionstringNew description.
tagsstring[]Replacement tag set.
folder_idstringNew folder UUID, or null to move to root.
delete_promptprompts:delete

Permanently delete a prompt.

Inputs
prompt_idstringrequiredThe prompt's UUID.
confirmtruerequiredMust be literal true to guard against accidental deletes.

Blocks

5 tools

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

list_blocksblocks:read

List all blocks for a prompt in sort order.

Inputs
prompt_idstringrequiredThe prompt's UUID.
create_blockblocks:write

Create a new block on a prompt.

Inputs
prompt_idstringrequiredThe prompt's UUID.
type'role' | 'context' | 'instructions' | 'guardrails' | 'output_format' | 'custom'requiredBlock type — determines compilation order and styling.
titlestringrequiredSection heading rendered as ## Title.
contentstringMarkdown body of the block. Supports {{variable}} interpolation.
sort_ordernumberPosition in the block list. Defaults to end of list.
enabledbooleanWhether the block participates in compilation (default: true).
is_requiredbooleanMarks the block as required for validation purposes.
update_blockblocks:write

Update block fields.

Inputs
block_idstringrequiredThe block's UUID.
titlestringNew section heading.
contentstringNew markdown body.
enabledbooleanToggle compilation participation.
sort_ordernumberNew position in the block list.
delete_blockblocks:write

Permanently delete a block from a prompt.

Inputs
block_idstringrequiredThe block's UUID.
reorder_blocksblocks:write

Reorder all blocks on a prompt in one atomic call.

Inputs
prompt_idstringrequiredThe prompt's UUID.
block_idsstring[]requiredBlock UUIDs in the desired final order.

Variables

3 tools

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

list_variablesvariables:read

List all variables defined on a prompt.

Inputs
prompt_idstringrequiredThe prompt's UUID.
upsert_variablevariables:write

Create or update a variable on a prompt.

Inputs
prompt_idstringrequiredThe prompt's UUID.
keystringrequiredVariable name. Must match ^[a-zA-Z_][a-zA-Z0-9_]*$.
default_valuestringFallback used when no value is passed at fetch time.
descriptionstringHuman-readable description for teammates and the dashboard.
delete_variablevariables:write

Delete a variable from a prompt.

Inputs
variable_idstringrequiredThe variable's UUID.

Versions

5 tools

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

list_versionsversions:read

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

Inputs
prompt_idstringrequiredThe prompt's UUID.
save_draft_versionversions:write

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

Inputs
prompt_idstringrequiredThe prompt's UUID.
changelog_notestringOptional note describing what changed in this draft.
publish_versionversions:publish

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

Inputs
version_idstringrequiredThe version's UUID.
changelog_notestringOptional note attached to the publish event.

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

rollback_to_versionversions:write

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

Inputs
version_idstringrequiredThe version to restore from.
diff_versionsversions:read

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

Inputs
version_a_idstringrequiredThe base version's UUID.
version_b_idstringrequiredThe target version's UUID.

Test Cases

4 tools

Manage reusable test inputs for evaluation runs.

list_test_casestest_cases:read

List all test cases attached to a prompt.

Inputs
prompt_idstringrequiredThe prompt's UUID.
create_test_casetest_cases:write

Create a new test case for a prompt.

Inputs
prompt_idstringrequiredThe prompt's UUID.
namestringrequiredDisplay name of the test case.
input_textstringrequiredUser input to feed the prompt during evaluation.
variable_overridesRecord<string, string>Per-test variable values that override defaults.
expected_outputstringReference output for grading.
evaluation_criteriaobjectGrader config (contains, regex_match, similarity_score, etc.).
update_test_casetest_cases:write

Update fields on an existing test case.

Inputs
test_case_idstringrequiredThe test case's UUID.
namestringNew display name.
input_textstringNew user input.
variable_overridesRecord<string, string>New override map.
expected_outputstringNew reference output.
evaluation_criteriaobjectNew grader config.
delete_test_casetest_cases:write

Delete a test case permanently.

Inputs
test_case_idstringrequiredThe test case's UUID.