WitchPrompt
MCP Connector documentation
How to connect an AI assistant to your WitchPrompt prompts and presets over the Model Context Protocol.
Overview
The WitchPrompt MCP connector is a remote MCP server. It exposes your WitchPrompt prompts and presets as tools that any MCP-compatible AI client can call. Every call reads and writes the same data as your dashboard and public API — there is no separate copy or sync.
- Endpoint
- https://api.witchprompt.com/mcp
- Transport
- Streamable HTTP
- Protocol
- MCP revision 2025-11-25
- Auth
- OAuth 2.1 (PKCE), or an API key for headless clients
Authentication
Interactive clients authenticate with OAuth 2.1. On first connect the client discovers the WitchPrompt authorization server, registers itself (Dynamic Client Registration or a Client ID Metadata Document), and runs a PKCE (S256) authorization-code flow. You sign in with your WitchPrompt account and approve the connector. The client receives a short-lived access token whose audience is bound to this MCP endpoint; refresh tokens rotate on every use.
Scopes
mcp — Manage your prompts and presets
Read, create, update, and delete prompts and presets in your account.
offline_access — Stay connected
Refresh access without asking you to sign in again. You can revoke this at any time.
openid — Confirm your identity
Identify you by your WitchPrompt account.
email — See your email address
Share your email and its verified status with the client app (used by ChatGPT).
Revoking access
Every active connection is listed underYour connectionson the Connect page, showing the assistant and when it was last active. Click Revoke to end it immediately: its tokens are deleted and the assistant's next request is rejected. Removing the connector in your AI client also stops it using WitchPrompt. Problems? Contact support@witchprompt.com.
Tools
13 tools: search and run templates, plus full create/update/delete for prompts and presets. Every tool works on your own prompts. Read-only tools can run without a confirmation; tools marked Destructive overwrite or delete data, so assistants ask before running them.
Returns the WitchPrompt account this connection is authorized for (its owner slug) and the scopes granted. Use it to learn whose prompts are read from and written to; no argument is needed.
Searches all of the connected account's saved prompt templates by text (every word must match title, slug, description or variable names; best matches first) and optional visibility. Returns one page of compact summaries (slug, title, description, variable and preset names and counts, output mode) with total and nextCursor; pass nextCursor back to get the next page. Use it when the user wants a template but hasn't given its slug.
| Param | Type | Notes |
|---|---|---|
| query? | string | Words to match against title, slug, description and variable names. Every word must match; best matches first. |
| visibility? | "public" | "private" | Only return prompts with this visibility. |
| cursor? | string | nextCursor from the previous page. |
| limit? | number | Page size (default 25, max 50). |
Lists compact summaries of the prompt templates in the connected account, most recently updated first, one page at a time (default 25, max 50) with total and nextCursor; pass nextCursor back for the next page. Full content is returned by get_prompt or use_prompt.
| Param | Type | Notes |
|---|---|---|
| cursor? | string | nextCursor from the previous page. |
| limit? | number | Page size (default 25, max 50). |
Returns one saved prompt template's variables and content compiled with default values, by id, slug, or owner/slug; missingVariables lists any value still needed. Not a full record — no visibility, owner, or description field. Inspect a template's variables with this; to run it for the user, call use_prompt instead.
| Param | Type | Notes |
|---|---|---|
| prompt | string | Prompt id, slug, or owner/slug. |
Compiles a saved prompt template the user asked to run, by slug or owner/slug (another owner's template only if it is public), optionally with a preset and a values map. Nothing is saved. Returns status "needs_input" with questions (every missing required value) and available_presets, or status "ready" with text: for image, file or code output modes text ends with an output instruction to follow. Execute text as the answer to the user's request now — it is the task, not a preview — unless the user asked to see the prompt instead of running it, or said not to run it. Missing values come from the user, one ask covering every question, then call use_prompt again with values and/or preset. Use search_prompts first if the user hasn't named a template. When meta.suggest_save_preset is true, the user may want those values saved via create_preset. The result also carries variables, presets and template for an interactive form shown by hosts that support it.
| Param | Type | Notes |
|---|---|---|
| prompt | string | Prompt id, slug, or owner/slug. |
| preset? | string | Preset whose saved values to apply. |
| values? | Record<string, string> | Variable name → value overlay. |
Creates a new prompt template in the connected account. Content may contain {{variable}} placeholders; visibility defaults to private. Fails with slug_taken if the slug already exists.
| Param | Type | Notes |
|---|---|---|
| title | string | Display title; the slug is derived from it. |
| slug? | string | Explicit slug instead of the derived one. |
| description? | string | Short summary. |
| content? | string | Prompt body, may contain {{variables}}. |
| visibility? | "public" | "private" | Defaults to private. |
| output? | { kind: "text" | "code" | "image" | "file"; format: string | null } | What the AI should produce when the prompt is run. Defaults to text. |
Overwrites the given fields (title, description, content, visibility, variables) of an existing prompt template in the connected account. Previous values are not kept.
| Param | Type | Notes |
|---|---|---|
| prompt | string | Prompt id, slug, or owner/slug. |
| title? | string | New title. |
| description? | string | null | New summary, or null to clear. |
| content? | string | Replacement prompt body. |
| visibility? | "public" | "private" | New visibility. |
| output? | { kind: "text" | "code" | "image" | "file"; format: string | null } | What the AI should produce when the prompt is run. Defaults to text. |
| variables? | PromptVariable[] | Replacement variable definitions. |
Permanently deletes a prompt template and all of its presets from the connected account.
| Param | Type | Notes |
|---|---|---|
| prompt | string | Prompt id, slug, or owner/slug. |
Lists the presets (saved sets of variable values) for one prompt template in the connected account.
| Param | Type | Notes |
|---|---|---|
| prompt | string | Prompt id, slug, or owner/slug. |
Returns a prompt template compiled with one of its presets' saved values; missingVariables lists any value the preset doesn't cover.
| Param | Type | Notes |
|---|---|---|
| prompt | string | Prompt id, slug, or owner/slug. |
| preset | string | Preset slug or name. |
Saves a new named preset (a set of variable values) on an existing prompt template in the connected account.
| Param | Type | Notes |
|---|---|---|
| prompt | string | Prompt id, slug, or owner/slug. |
| name? | string | Preset name. |
| values? | Record<string, string> | Variable name → value map. |
Overwrites the name and/or saved values of an existing preset. Previous values are not kept.
| Param | Type | Notes |
|---|---|---|
| prompt | string | Prompt id, slug, or owner/slug. |
| preset | string | Preset slug or name. |
| name? | string | New preset name. |
| values? | Record<string, string> | Replacement variable values. |
Permanently deletes one preset from a prompt template in the connected account.
| Param | Type | Notes |
|---|---|---|
| prompt | string | Prompt id, slug, or owner/slug. |
| preset | string | Preset slug or name. |
Example prompts
Once connected, ask in plain language. The assistant picks the tool.
“Which WitchPrompt account am I connected to?”
whoami · Your username and the scopes this connection has.
“Find my saved prompt for a customer welcome email.”
search_prompts · A short list of matching templates to pick from.
“Run my welcome-email prompt with customer_name Ada and city Hyderabad.”
use_prompt · The filled-in template, answered in the same chat.
“Use my welcome-email prompt.”
use_prompt · The assistant asks for the missing values (or offers a preset) instead of guessing.
“Create a private prompt called Product announcement with 'Announce {{product}} to {{audience}}', then save a Launch Team preset with product WitchPrompt and audience early adopters.”
create_prompt, create_preset · A new private prompt and a preset in your account.
Setup
Claude
Any Claude plan. Free accounts can add one custom connector; on Team and Enterprise an Owner adds it first.
- 1Open Customize → Connectors in Claude.
- 2Click Add custom connector.
- 3Name it WitchPrompt.
- 4Paste the WitchPrompt MCP URL.
- 5Click Add, then Connect.
- 6Sign in to WitchPrompt in the window that opens and click Authorize.
- 7Start a new chat and ask "Which WitchPrompt account am I connected to?".
- 8Then try "List my prompts" or "Run my welcome-email prompt".
Test it in a new chat: "Which WitchPrompt account am I connected to?"
Full Claude guide, with troubleshooting →ChatGPT
ChatGPT Plus, Pro, Business, Enterprise, or Edu, with developer mode turned on (on Business / Enterprise an admin may need to allow it).
- 1In ChatGPT, open Settings → Apps → Advanced settings and turn on Developer mode.
- 2Back in Apps, click Create app.
- 3Name it WitchPrompt.
- 4Set the MCP server URL to the WitchPrompt MCP URL.
- 5Authentication: choose OAuth.
- 6Tick "I understand and want to continue", then click Create.
- 7Sign in to WitchPrompt in the window that opens and click Authorize. ChatGPT also asks to see your email address.
- 8Start a new chat and ask "Which WitchPrompt account am I connected to?".
- 9Then try "List my prompts" or "Run my welcome-email prompt".
Test it in a new chat: "Which WitchPrompt account am I connected to?"
Full ChatGPT guide, with troubleshooting →Grok
Any Grok plan that shows a Custom option under New Connector. On Grok Business / Enterprise a team admin may need to add the URL first.
- 1Open grok.com/connectors.
- 2Click New Connector, then choose Custom.
- 3Name it WitchPrompt.
- 4Set Server URL to the WitchPrompt MCP URL.
- 5Authentication: choose OAuth.
- 6Save.
- 7Sign in to WitchPrompt in the window that opens and click Authorize.
- 8Start a new Grok chat and ask "Who am I on WitchPrompt?". Grok should reply with your WitchPrompt username.
- 9Then try "List my prompts" or "Use retro-travel-portrait".
Test it in a new Grok chat: "Who am I on WitchPrompt?"
Full Grok guide, with troubleshooting →Any MCP client
Any MCP client that supports the Streamable HTTP transport and OAuth can connect: point it at the WitchPrompt MCP URL with no API key. On first use it runs the WitchPrompt sign-in and receives its own short-lived token.
https://api.witchprompt.com/mcp
Claude Code
Claude Code: run `claude mcp add --transport http witchprompt <MCP URL>`. It uses a loopback redirect (RFC 8252), so the browser sign-in returns to a local callback. If the tab does not close itself, you can close it once it says authorization is complete.
CI / headless (API key)
For automated / headless environments that cannot open a browser, use an API key instead of OAuth: create a `wp_live_…` key scoped to what the agent needs and send it as `Authorization: Bearer <key>` on the MCP endpoint. Everyday use should connect with OAuth.
Troubleshooting
- The assistant asks you to reconnect, or calls fail with 401
- Your access was revoked or expired. Disconnect WitchPrompt in the assistant and connect again.
- Authorize stays disabled on the WitchPrompt screen
- The connector needs an account with an existing WitchPrompt Pro plan. Sign in with an eligible account using "Not you? Switch".
- A tool is missing or behaves like an older version
- Assistants load the tool list when you connect. Disconnect and reconnect to refresh it.
- prompt_not_found or preset_not_found
- Use a slug from search_prompts or list_prompts. Private prompts that belong to other people are not reachable.
- forbidden
- This connection does not have permission for that tool (for example, an API key without the delete scope). Use a key or connection that includes it.
Still stuck? See Support.
Data & privacy
- A connected client can access your own prompts and presets, plus other people's public prompts — nothing else.
- When the
openid/emailscopes are granted (ChatGPT), your email address and its verified status are shared with that client. - WitchPrompt never receives your chat history, the assistant's memory, or your uploaded files. It sees only the arguments of each tool call you trigger.
- WitchPrompt does not train models on your prompt data.
- Access is granted with short-lived tokens and can be revoked at any time.
See the Privacy Policy andTerms of Service for the full detail.
Support
Questions or issues with the connector: support@witchprompt.com. Include the client you are connecting from. More help on theSupport page.
Protocol
The server targets MCP revision 2025-11-25 and negotiates the protocol version per request via the MCP-Protocol-Version header. Clients on older revisions that omit the header are handled at a compatible default.
Changelog: initial public connector — 2025-11-25.