Prompts API & MCP Server Documentation

prompts.chat provides an MCP-first API for searching and discovering AI prompts programmatically. Use the MCP endpoint directly with any MCP-compatible client, or make standard HTTP requests.

MCP-First API

Our API is built on the Model Context Protocol (MCP), enabling seamless integration with AI assistants, IDEs, and automation tools. The same endpoint works for both MCP clients and traditional REST-style requests.

# MCP Endpoint

POST https://prompts.chat/api/mcp

Using with MCP Clients

Add prompts.chat to your MCP client configuration. Choose your client and connection type below:

{
  "mcp": {
    "servers": {
      "prompts.chat": {
        "type": "http",
        "url": "https://prompts.chat/api/mcp"
      }
    }
  }
}

Remote connects directly to prompts.chat API. Local runs the MCP server locally via npx.

Authentication

Most API features work without authentication. However, to save prompts via MCP or access your private prompts, you need to authenticate using an API key.

Generate an API Key

Go to Settings to generate your API key. Keys start with pchat_.

Using the API Key

Pass your API key via the PROMPTS_API_KEY header. An Authorization: Bearer header, x-api-key header or ?api_key= query parameter also work.

# Remote: HTTP transport with headers
"prompts-chat": {
  "url": "https://prompts.chat/api/mcp",
  "headers": {
    "PROMPTS_API_KEY": "pchat_your_api_key_here"
  }
}

# Local: stdio transport with environment variable
"prompts-chat": {
  "command": "npx",
  "args": ["-y", "@fkadev/prompts.chat-mcp"],
  "env": {
    "PROMPTS_API_KEY": "pchat_your_api_key_here"
  }
}

# Or via curl (remote)
curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "PROMPTS_API_KEY: pchat_your_api_key_here" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Remote (HTTP) sends requests to prompts.chat with the API key in headers. Local (stdio) runs the MCP server locally via npx with the API key as an environment variable. With authentication, you can use the save_prompt and save_bot tools and search results will include your private prompts. The endpoint is stateless: every POST is answered with a plain JSON response, so no session or SSE stream is needed.

MCP Prompts

All public prompts are exposed as native MCP prompts. This allows MCP clients to list and use prompts directly via slash commands or prompt pickers. You can filter prompts by category or tag using URL query parameters.

# Filter by users (one or more usernames)
"prompts-chat": {
  "url": "https://prompts.chat/api/mcp?users=f,torvalds"
}

# Filter by categories
"prompts-chat": {
  "url": "https://prompts.chat/api/mcp?categories=coding,marketing"
}

# Filter by tags
"prompts-chat": {
  "url": "https://prompts.chat/api/mcp?tags=chatgpt,writing"
}

# Combine filters
"prompts-chat": {
  "url": "https://prompts.chat/api/mcp?users=f&categories=coding&tags=js"
}

prompts/list

Browse all available prompts with pagination support. Each prompt lists its variables as arguments; variables without a default are required.

prompts/get

Retrieve a prompt by ID. Variables (${name} or ${name:default}) are automatically substituted with provided arguments.

# List prompts
curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "prompts/list"}'

# Get a specific prompt with arguments
curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "prompts/get",
    "params": {
      "name": "code-review-assistant",
      "arguments": { "topic": "AI safety" }
    }
  }'

Available Tools

search_prompts

Search for AI prompts by keyword. Returns matching prompts with title, description, content, author, category, and tags.

Parameter	Type	Required	Description
query	string	Yes	Search query to find relevant prompts
limit	number	No	Maximum results (default: 10, max: 50)
cursor	string	No	The `nextCursor` of a previous result, for the next page
type	string	No	Filter by type: `TEXT`, `STRUCTURED`, `IMAGE`, `VIDEO`, `AUDIO`
category	string	No	Filter by category slug
tag	string	No	Filter by tag slug

get_prompt

Get a prompt by ID, with its template variables (like ${variable} or ${variable:default}). Pass variables to get the prompt filled in.

Parameter	Type	Required	Description
id	string	Yes	The ID of the prompt to retrieve
variables	object	No	Values for the template variables, by name

Filling Variables

The result lists the prompt's variables. With variables given, content holds the filled prompt and originalContent the template. Variables with a default (after the colon) are optional; any required ones still missing are listed in missingVariables, so the agent can ask the user and call again.

save_promptRequires Auth

Save a new prompt to your account. Requires API key authentication. Prompts are private by default unless you've changed the default in your settings.

Parameter	Type	Required	Description
title	string	Yes	Title of the prompt (max 200 chars)
content	string	Yes	The prompt content. Can include variables like ${var}
description	string	No	Optional description (max 500 chars)
tags	string[]	No	Array of tag names (max 10)
category	string	No	Category slug
isPrivate	boolean	No	Override default privacy setting
type	string	No	`TEXT` (default), `STRUCTURED`, `IMAGE`, `VIDEO`, `AUDIO`

# Save a prompt via MCP
curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "PROMPTS_API_KEY: pchat_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "save_prompt",
      "arguments": {
        "title": "My Code Review Prompt",
        "content": "Review this code for ${language} best practices:\n\n${code}",
        "description": "A helpful code review assistant",
        "tags": ["coding", "review"],
        "isPrivate": false
      }
    }
  }'

improve_promptRequires Auth

Transform a basic prompt into a well-structured, comprehensive prompt using AI. Searches for similar prompts for inspiration and generates improved versions.

Parameter	Type	Required	Description
prompt	string	Yes	The prompt to improve (max 10,000 chars)
outputType	string	No	Content type: `text` (default), `image`, `video`, `sound`
outputFormat	string	No	Response format: `text` (default), `structured_json`, `structured_yaml`

# Improve a prompt via MCP
curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "PROMPTS_API_KEY: pchat_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "improve_prompt",
      "arguments": {
        "prompt": "write a blog post about AI",
        "outputType": "text",
        "outputFormat": "text"
      }
    }
  }'

save_skillRequires Auth

Save a new Agent Skill to your account. Skills are multi-file prompts that can include SKILL.md (required), reference docs, scripts, and configuration files. Perfect for creating comprehensive coding agent skills.

Parameter	Type	Required	Description
title	string	Yes	Title of the skill (max 200 chars)
files	array	Yes	Array of {filename, content}. Must include `SKILL.md`
description	string	No	Optional description (max 500 chars)
tags	string[]	No	Array of tag names (max 10)
category	string	No	Category slug
isPrivate	boolean	No	Override default privacy setting

# Save a skill via MCP
curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "PROMPTS_API_KEY: pchat_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "save_skill",
      "arguments": {
        "title": "PDF Processing Skill",
        "description": "Comprehensive PDF manipulation toolkit",
        "files": [
          {"filename": "SKILL.md", "content": "# PDF Processing\n\nThis skill helps with PDF manipulation..."},
          {"filename": "reference.md", "content": "# API Reference\n\n..."},
          {"filename": "scripts/extract.py", "content": "import pypdf\n..."}
        ],
        "tags": ["pdf", "documents"]
      }
    }
  }'

add_file_to_skillRequires Auth

Add a new file to an existing Agent Skill. Use this to add reference docs, scripts, or configuration files.

Parameter	Type	Required	Description
skillId	string	Yes	ID of the skill to add the file to
filename	string	Yes	File path (e.g., `reference.md`, `scripts/helper.py`)
content	string	Yes	File content

remove_file_from_skillRequires Auth

Remove a file from an existing Agent Skill. Cannot remove SKILL.md as it is required.

Parameter	Type	Required	Description
skillId	string	Yes	ID of the skill to remove the file from
filename	string	Yes	File path to remove (cannot be SKILL.md)

get_skill

Get an Agent Skill by ID, including all its files (SKILL.md, reference docs, scripts, etc.). Returns skill metadata and file contents. Public skills are accessible without authentication; private skills require API key authentication.

Parameter	Type	Required	Description
id	string	Yes	The ID of the skill to retrieve

# Get a skill via MCP
curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_skill",
      "arguments": {
        "id": "skill_id_here"
      }
    }
  }'

search_bots

Search the public bots directory. Returns bot summaries; use get_bot for the full definition and install instructions. With semantic: true and AI search enabled, results are ranked by meaning; otherwise keyword search is used and searchMode says so.

Parameter	Type	Required	Description
query	string	No	Keywords; separate alternatives with commas
platform	string	No	Only bots for this platform, e.g. `HERMES`
category	string	No	Category slug (includes its subcategories)
tags	string[]	No	Tag slugs; every tag must match
sort	string	No	`newest` (default), `oldest` or `upvotes`
semantic	boolean	No	Rank by meaning using AI search when available
limit / cursor	number / string	No	Page size (default 10, max 50) and the `nextCursor` of the previous page

get_bot

Get a bot by id (or its id_slug URL segment) or slug: its instructions, routines, skills and connectors, an install entry per platform (one-click link, a prompt to paste into the agent, or a CLI command) and the bots it works well with. Public and unlisted bots are visible to everyone; private bots only to their owner.

curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
       "params": {"name": "get_bot", "arguments": {"slug": "inbox-triage"}}}'

save_botRequires Auth

Create or update one of your own bots, so an agent connected over MCP can back up its own definition. It is an idempotent upsert: it updates your bot matching id, else slug, else name (case-insensitive), and only creates a bot when none matches. Sending the same definition again changes nothing. On update, omitted optional fields keep their stored values. Bots go through the same validation, limits and moderation as the bot form, and new bots are private by default unless your settings say otherwise.

Parameter	Type	Required	Description
name	string	Yes	Bot name (max 200 chars)
instructions	string	Yes	The bot's standing instructions (its system prompt)
platforms	string[]	Yes	One or more of `GROK_BOT`, `OPENCLAW`, `HERMES`, `AUTOGPT`, `DOTS`, `DUET`, `MUSE`
id	string	No	Update this bot; it must be one of yours
slug	string	No	Match your existing bot by slug (falls back to matching by name)
description	string	No	Short summary (max 500 chars)
icon / color	string \| null	No	A preset icon and color from the bot form; null resets to the default
installUrl	string \| null	No	https one-click install link (Grok Bot template link)
routines	array	No	{name, type: "schedule" \| "event", trigger, triggerLabel?, prompt} (max 20, replaces all)
skills	array	No	{name, description?, source?} (max 20, replaces all)
connectors	string[]	No	Connectors the user must connect, e.g. Gmail (max 20, replaces all)
category	string \| null	No	Category slug; null removes it
tags	string[]	No	Tag names (max 10, replaces all)
isPrivate	boolean	No	Override the default privacy setting (applies on create; on update only when given)

# Back up a bot via MCP (run it again any time to sync changes)
curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "PROMPTS_API_KEY: pchat_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "save_bot",
      "arguments": {
        "name": "Inbox Triage",
        "description": "Sorts my inbox every morning",
        "instructions": "You triage my email. Label, archive and summarize...",
        "platforms": ["OPENCLAW", "HERMES"],
        "icon": "inbox",
        "color": "sky",
        "routines": [{
          "name": "Morning triage",
          "type": "schedule",
          "trigger": "0 8 * * *",
          "triggerLabel": "Every day at 08:00",
          "prompt": "Triage unread email and send me a summary."
        }],
        "connectors": ["Gmail"],
        "tags": ["email"]
      }
    }
  }'

# Result: {"success": true, "action": "created" | "updated" | "unchanged",
#          "changedFields": [...], "bot": {"id": "...", "slug": "inbox-triage", ...}, "link": ...}

list_my_botsRequires Auth

List your own bots, including private ones, newest first, with their ids and slugs.

Parameter	Type	Required	Description
limit	number	No	Maximum bots to return (default 50, max 100)
cursor	string	No	The `nextCursor` of a previous result (`offset` still works but is deprecated)

get_my_botRequires Auth

Get the full definition of one of your bots (instructions, platforms, routines, skills, connectors and install options), including private ones, for example to restore a bot from its backup.

Parameter	Type	Required	Description
id	string	One of	Bot id
slug	string	One of	Bot slug, used when no id is given

MCP Resources

Prompts, skills and bots can also be read as MCP resources. Tool results include resource_link entries pointing at them, and resources/list lists your own items when you are authenticated. Resources follow the same visibility rules as the tools.

prompts-chat://prompts/{id} : a prompt as Markdown

prompts-chat://skills/{id} : every file of a skill

prompts-chat://skills/{id}/files/{path} : one skill file

prompts-chat://bots/{id} : a bot's definition and setup steps as Markdown

curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "resources/read",
       "params": {"uri": "prompts-chat://bots/bot_id_here"}}'

MCP Protocol Examples

Initialize Connection

curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "my-app", "version": "1.0.0" }
    }
  }'

List Available Tools

curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

Search Prompts

curl -X POST https://prompts.chat/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_prompts",
      "arguments": {
        "query": "code review",
        "limit": 5
      }
    }
  }'

Response Format

Tools return their result as structuredContent, described by the tool's outputSchema, and the same JSON as a text block for older clients, followed by resource links. Errors set isError with {"error": "...", "code": "..."}. For example, search_prompts returns:

{
  "query": "code review",
  "count": 2,
  "prompts": [
    {
      "id": "abc123",
      "title": "Code Review Assistant",
      "description": "A prompt for conducting thorough code reviews",
      "contentPreview": "You are an expert code reviewer...",
      "type": "TEXT",
      "author": "username",
      "category": "Development",
      "tags": ["coding", "review", "development"],
      "votes": 42,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "link": "https://prompts.chat/prompts/abc123_code-review-assistant"
    }
  ],
  "nextCursor": "Mg"
}

Improve Prompt APIRequires Auth

Transform basic prompts into well-structured, comprehensive prompts using AI. The API uses embeddings to find similar prompts for inspiration and generates improved versions while preserving the original intent. Requires API key authentication.

Parameter	Type	Required	Description
prompt	string	Yes	The prompt to improve (max 10,000 chars)
outputType	string	No	Content type: `text` (default), `image`, `video`, `sound`
outputFormat	string	No	Response format: `text` (default), `structured_json`, `structured_yaml`

# Improve a prompt
curl -X POST https://prompts.chat/api/improve-prompt \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pchat_your_api_key_here" \
  -d '{
    "prompt": "write a blog post about AI",
    "outputType": "text",
    "outputFormat": "text"
  }'

Response Format

{
  "original": "write a blog post about AI",
  "improved": "You are an expert technology writer...

## Task
Write an engaging blog post...",
  "outputType": "text",
  "outputFormat": "text",
  "inspirations": [
    { "title": "Blog Writer", "similarity": 85 },
    { "title": "Content Creator", "similarity": 72 }
  ],
  "model": "gpt-4o"
}

Try It Out

Your Prompt

Output Type

Output Format

# API Request

curl -X POST /api/improve-prompt \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "",
    "outputType": "text",
    "outputFormat": "text"
  }'

REST API

Use the standard REST endpoint to search and retrieve prompts:

# Search prompts via REST
curl "https://prompts.chat/api/prompts?q=code+review&perPage=10"

# Get prompt by ID
curl "https://prompts.chat/api/prompts/{id}"

Rate Limits

The API is public and free to use. Please be respectful with request frequency. For high-volume usage, consider self-hosting your own instance.

Support

For issues and feature requests, please open a GitHub Issue.

API Documentation

MCP-First API

Using with MCP Clients

Authentication

MCP Prompts

Available Tools

search_prompts

get_prompt

save_promptRequires Auth

improve_promptRequires Auth

save_skillRequires Auth

add_file_to_skillRequires Auth

remove_file_from_skillRequires Auth

get_skill

search_bots

get_bot

save_botRequires Auth

list_my_botsRequires Auth

get_my_botRequires Auth

MCP Resources

MCP Protocol Examples

Initialize Connection

List Available Tools

Search Prompts

Response Format

Improve Prompt APIRequires Auth

Try It Out

REST API

Rate Limits

Support