MCP Reference
Promptmark’s MCP server exposes 38 tools across 9 categories. All tools require authentication via Bearer JWT or API key.
Prompt Tools (10)
list_prompts
Prompts
List prompts with optional filtering.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
search |
string | No | Filter by title or content |
tag |
string | No | Filter by tag name |
collection_id |
string | No | Filter by collection ID |
type_id |
string | No | Filter by prompt type |
is_template |
boolean | No | Filter templates only (true) or prompts only (false) |
is_remix |
boolean | No | Filter remixes only (true) or exclude (false) |
limit |
integer | No | Max results (default 50, max 100) |
offset |
integer | No | Pagination offset (default 0) |
get_prompt
Prompts
Get a specific prompt by ID.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | The prompt ID |
create_prompt
Prompts
Create a new prompt.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
title |
string | Yes | Prompt title |
prompt |
string | Yes | Prompt content (use {{var}} for templates) |
notes |
string | No | Private notes |
is_public |
boolean | No | Public visibility (default false) |
is_remixable |
boolean | No | Allow remixing (default false) |
tags |
string | No | JSON array of tags, e.g. ["ai", "coding"] |
type_id |
string | No | Type: general, system, query, text-to-image, text-to-video, text-to-speech, text-to-code, agent |
collection_id |
string | No | Collection to assign to |
remixed_id |
string | No | Source prompt ID (creates a remix) |
models |
string | No | JSON array of model IDs |
self_rating |
number | No | Rating 1-5 (0 = no rating) |
update_prompt
Prompts
Update an existing prompt. Only provided fields are changed.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Prompt ID to update |
title |
string | No | New title |
prompt |
string | No | New content |
notes |
string | No | New notes |
is_public |
boolean | No | Public visibility |
is_remixable |
boolean | No | Allow remixing |
tags |
string | No | JSON array of tags |
type_id |
string | No | Prompt type |
collection_id |
string | No | Collection ID (empty string to remove) |
models |
string | No | JSON array of model IDs |
self_rating |
number | No | Rating 1-5 |
delete_prompt
Prompts
Soft-delete a prompt.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Prompt ID to delete |
search_prompts
Prompts
Search prompts by title, tags, or visibility.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
query |
string | No | Search term for title and notes |
tags |
array | No | Filter by tags (must match ALL) |
is_public |
boolean | No | Filter by visibility |
limit |
integer | No | Max results (default 50) |
list_tags
Prompts
List all unique tags across your prompts.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
include_counts |
boolean | No | Include usage count per tag (default false) |
limit |
integer | No | Max tags to return (default 100) |
get_prompt_schema
Prompts
Get the template variable schema for a prompt.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Prompt ID |
Returns: Variable names, types, defaults, options, and required status.
render_prompt
Prompts
Render a prompt template by substituting variables.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Prompt template ID |
variables |
object | No | Key-value pairs of variable values |
Returns: The rendered prompt text with variables substituted.
validate_prompt_inputs
Prompts
Validate variable values before rendering.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Prompt template ID |
variables |
object | Yes | Key-value pairs to validate |
Returns: Validation errors for invalid or missing required values.
Collection Tools (6)
list_collections
Collections
List all collections.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
include_counts |
boolean | No | Include prompt count per collection (default true) |
get_collection
Collections
Get a specific collection with optional prompt list.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Collection ID |
include_prompts |
boolean | No | Include prompt IDs (default false) |
create_collection
Collections
Create a new collection.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Collection name |
description |
string | No | Description |
icon |
string | No | Icon identifier (default “folder”) |
color |
string | No | Color: gray, red, orange, yellow, green, cyan, blue, purple, pink (default “gray”) |
is_public |
boolean | No | Public visibility (default false) |
update_collection
Collections
Update a collection. Only provided fields are changed.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Collection ID |
name |
string | No | New name |
description |
string | No | New description |
icon |
string | No | New icon |
color |
string | No | New color |
is_public |
boolean | No | Public visibility |
delete_collection
Collections
Delete a collection. Prompts in it become uncategorized.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Collection ID |
assign_prompt_to_collection
Collections
Move a prompt to a collection or remove from its current collection.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
prompt_id |
string | Yes | Prompt ID |
collection_id |
string | No | Target collection ID (empty to remove) |
Tag Tools (1)
rename_tag
Tags
Rename a tag across all prompts that use it.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
old_name |
string | Yes | Current tag name |
new_name |
string | Yes | New tag name |
Remix Tools (1)
list_remixes
Remix
List all remixes (prompts derived from other prompts).
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
limit |
integer | No | Max results (default 50) |
Version Tools (3)
get_prompt_versions
Versions
Get version history for a prompt.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
prompt_id |
string | Yes | Prompt ID |
get_prompt_version
Versions
Get a specific version snapshot.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
version_id |
string | Yes | Version ID |
restore_prompt_version
Versions
Restore a prompt to a previous version. Snapshots the current state first.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
prompt_id |
string | Yes | Prompt ID |
version_id |
string | Yes | Version ID to restore |
Response Tools (4)
capture_response
Responses
Capture an AI response for a prompt.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
prompt_id |
string | Yes | Prompt ID |
model_id |
string | Yes | Model name/ID (e.g., “gpt-4”, “claude-3-opus”) |
content |
string | Yes | Response content |
metadata |
object | No | Optional metadata (tokens, latency, temperature) |
list_captured_responses
Responses
List captured responses, newest first.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
prompt_id |
string | No | Filter by prompt ID |
limit |
integer | No | Max results (default 20, max 100) |
offset |
integer | No | Pagination offset |
get_captured_response
Responses
Get full response content by ID.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Response ID |
delete_captured_response
Responses
Permanently delete a captured response.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Response ID |
Achievement Tools (3)
list_achievements
Achievements
Get the user’s achievement state. Returns all 6 achievements with unlock status.
Parameters: None.
dismiss_onboarding
Achievements
Hide the First Steps widget from the dashboard. The trophy case in Settings remains visible.
Parameters: None.
restore_onboarding
Achievements
Restore the First Steps widget to the dashboard.
Parameters: None.
Scan Tools (1)
acknowledge_scan
Scans
Acknowledge a safety scan issue. Transitions the flag from HAS (1) to HAD (2), allowing the prompt to be published.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
prompt_id |
string | Yes | Prompt ID |
category |
string | Yes | Scan category: pii, injection, secrets, or danger |
Conversation Tools (9)
list_conversations
Conversations
List conversations with optional search and source filtering.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
page |
integer | No | Page number (1-indexed, default 1) |
search |
string | No | Search conversations by title |
source |
string | No | Filter by source: native, claude, chatgpt, json, markdown |
get_conversation
Conversations
Get a conversation by ID with optional messages.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | The conversation ID to retrieve |
include_messages |
boolean | No | Include messages in response (default true) |
message_limit |
integer | No | Max messages to return (default 50, max 200) |
create_conversation
Conversations
Create a new conversation with a model and optional system prompt.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
title |
string | Yes | Conversation title |
model_id |
string | Yes | AI model ID for this conversation (e.g. anthropic/claude-sonnet-4) |
linked_prompt_id |
string | No | Link to an existing prompt ID for system prompt |
system_prompt |
string | No | Custom system prompt (overrides linked prompt) |
update_conversation
Conversations
Update conversation metadata (title, model, linked prompt, system prompt). Only provided fields are changed.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | The conversation ID to update |
title |
string | No | New conversation title (max 200 chars) |
model_id |
string | No | New model ID |
linked_prompt_id |
string | No | Prompt ID to link (empty string to unlink) |
system_prompt |
string | No | New system prompt text |
delete_conversation
Conversations
Delete a conversation (soft delete).
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | The conversation ID to delete |
send_message
Conversations
Send a message in a conversation and get the AI response (non-streaming). Requires an OpenRouter API key configured in Settings.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
conversation_id |
string | Yes | The conversation ID to send a message in |
content |
string | Yes | Message content to send |
prompt_reference_id |
string | No | Optional reference to a prompt ID |
import_conversation
Conversations
Import a conversation with messages from an external source.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
title |
string | Yes | Conversation title |
source |
string | No | Import source identifier (e.g. claude, chatgpt) |
model |
string | No | Model ID used in the conversation |
messages |
array | Yes | Array of message objects (see below) |
Each object in messages has:
| Name | Type | Required | Description |
|---|---|---|---|
role |
string | Yes | Message role: system, user, or assistant |
content |
string | Yes | Message content |
list_conversation_messages
Conversations
List messages in a conversation with cursor-based pagination for large threads.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
conversation_id |
string | Yes | The conversation ID |
before |
string | No | Cursor: return messages created before this ISO 8601 timestamp |
limit |
integer | No | Max messages to return (default 50, max 200) |
link_conversation_prompt
Conversations
Link a conversation to an existing prompt for system prompt injection.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
conversation_id |
string | Yes | The conversation ID |
prompt_id |
string | Yes | The prompt ID to link |