AI apps (MCP) Pro

HandyPaste can share your snippet library with Claude and other AI apps that support the Model Context Protocol (MCP). Once connected, you can ask the AI to find a snippet, fill it in, or save something it wrote as a new snippet, and the snippets in your Prompts folder become ready-made prompts.

Nothing is shared until you turn it on, an AI app never sees your clipboard, and it can't delete anything for good.

What you can ask for

A few things that work once HandyPaste is connected:

• “Find my shipping delay reply and fill it in for Jordan, order 48213.”
• “What's my office address? Use it in this email.”
• “Save that reply as a snippet in Replies called Refund approved.”
• “Turn this message into a template that asks for the customer's name, and save it.”
• “Which of my snippets mention the refund policy?”
• “Move my old sign-off to Archive and rename it Old signature” (needs the second switch, see below).

The AI decides which HandyPaste tool to use. You'll see each call in the chat, and most apps ask before running one.

Set it up

You need HandyPaste Pro and HandyPaste installed on the Mac where the AI app runs.

1. Turn it on in HandyPaste

1. Open HandyPaste ▸ Settings… (⌘,) and choose the AI Apps tab.
2. Turn on Let AI apps use your snippets.
3. Leave Allow AI apps to change and delete snippets off unless you want the AI to edit or remove existing snippets. What each switch allows.

The AI Apps tab also has the exact text each app needs, with HandyPaste's real location on your Mac filled in. Use its buttons rather than typing the paths below.

2a. Connect Claude Desktop

1. In HandyPaste ▸ Settings ▸ AI Apps, click Copy Configuration next to Claude Desktop.
2. In Claude, choose Settings ▸ Developer ▸ Edit Config. Finder shows the file claude_desktop_config.json; open it in a text editor.
3. Paste the configuration:
   • If the file is empty or contains only {}, replace everything with what you copied.
   • If it already has an "mcpServers" section, add only the "handypaste" entry inside it, with a comma after the entry before it.
4. Save the file and quit and reopen Claude (⌘Q, not just closing the window).

What you paste looks like this, with the path to your copy of HandyPaste:

{
  "mcpServers": {
    "handypaste": {
      "args": ["--mcp"],
      "command": "/Applications/HandyPaste.app/Contents/MacOS/HandyPaste"
    }
  }
}

And merged with another server you already had:

{
  "mcpServers": {
    "some-other-server": { "command": "…", "args": ["…"] },
    "handypaste": {
      "args": ["--mcp"],
      "command": "/Applications/HandyPaste.app/Contents/MacOS/HandyPaste"
    }
  }
}

After restarting, HandyPaste appears among Claude's connected tools. Try: “Search my HandyPaste snippets for address.”

2b. Connect Claude Code

1. In HandyPaste ▸ Settings ▸ AI Apps, click Copy Command next to Claude Code.
2. Paste it in Terminal and press Return.

It looks like this:

claude mcp add --scope user handypaste -- '/Applications/HandyPaste.app/Contents/MacOS/HandyPaste' --mcp

--scope user makes HandyPaste available in every project. Check it with claude mcp list, or type /mcp inside Claude Code to see its status and tools. To remove it later: claude mcp remove --scope user handypaste.

2c. Other MCP apps

Any app that can launch a local (stdio) MCP server works. It needs two things:

Setting	Value
Command	/Applications/HandyPaste.app/Contents/MacOS/HandyPaste (the path of your copy)
Arguments	--mcp

Many apps use the same mcpServers format as Claude Desktop, so the copied configuration often works as it is. Check your app's documentation for where its MCP settings live.

If you move HandyPaste

The configuration points at HandyPaste's location. If you move the app, for example from Downloads to Applications, copy the configuration or command again and replace the old one.

3. Check it works

Ask the AI app something like “List my HandyPaste folders.” If it answers with your folders, you're set. If it says HandyPaste isn't sharing snippets, or that it's part of Pro, see Troubleshooting.

How it works

Claude (or another AI app)
   │  starts, and talks MCP over stdin/stdout
   ▼
HandyPaste --mcp          a small relay: no window, no access to your data
   │  private connection inside HandyPaste's sandbox
   ▼
HandyPaste (the app)      does every search and change, like when you use it
   │
   ▼
Your library              and iCloud sync, as usual

• The AI app starts HandyPaste --mcp, the same HandyPaste app in a relay mode. It opens no window and doesn't read your library itself.
• The relay passes messages to the running HandyPaste over a private connection inside HandyPaste's sandbox, which only your user account can open.
• If HandyPaste isn't running, the relay starts it quietly, without windows, just like when it opens at login, and waits up to 20 seconds for it to be ready.
• Every search and change happens in HandyPaste, through the same code as the library window. Changes sync to your other Macs, show up in the picker immediately, and snippets moved to Recently Deleted can be recovered as usual.
• HandyPaste itself connects to nothing new. The relay is local. But whatever the AI app reads is sent to that app's AI service, like anything else you share in a chat. See Privacy.

Tools

These are the tools HandyPaste offers. You don't call them yourself; the AI does, based on what you ask. Knowing them helps you phrase requests and understand what you see in the chat.

Tool	What it does	Changes your library?	Needs
search_snippets	Finds snippets by title, keyword and text	No	First switch
get_snippet	Returns a snippet, filled in like a paste	No	First switch
list_folders	Lists your folders	No	First switch
create_snippet	Saves a new snippet	Adds one	First switch
update_snippet	Changes a snippet's title, text or folder	Yes	Both switches
delete_snippet	Moves one snippet to Recently Deleted	Yes	Both switches

All results come back as JSON text the AI reads. Snippets are identified by an id (a UUID) that search_snippets returns.

search_snippets

Searches your snippets the way the picker does: by title, keyword and text, ignoring case and accents, best match first.

Parameter	Type	Description
query	text	Words to look for. Empty lists your snippets: favorites first, then recently used, then by title.
limit	number	How many results, 1–50. Default 20.

Returns each snippet's id, title, folder, keyword, whether it's a favorite, and the first 160 characters of its text, plus the total number of matches:

{
  "snippets": [
    {
      "favorite": true,
      "folder": "Replies",
      "id": "6F1C2E0A-3B7D-4C1E-9A55-2D8E4F1B7C90",
      "keyword": "qr",
      "preview": "Hi Name, Thanks for your message…",
      "title": "Quick Reply"
    }
  ],
  "total": 1
}

get_snippet

Returns one snippet's text, filled in as if you'd pasted it: dates and times, your variables, and included snippets.

Parameter	Type	Description
id	text	The snippet's id, from search_snippets.
title	text	Or its exact title (ignoring case), if there's no id. With duplicate titles, the oldest one is used, as with {{snippet:…}}.
fill	true/false	Fill in placeholders. Default true. With false, returns the text as the editor shows it, placeholders and all.
answers	object	Answers to the snippet's questions, by field name, e.g. {"Name": "Jordan"}.

Questions work like they do in the picker:

• A question with a default answer, and a choice list (its first choice), is filled in automatically unless answers says otherwise.
• A question with neither makes the call fail with a message naming the fields, for example: “Quick Reply” asks for “Name”. Ask the user, then call get_snippet again with answers. The AI then asks you and tries again.
• The result lists every question under fields, with its name, kind (text, multiline text or choice), options and default.

{
  "fields": [
    { "kind": "text", "label": "Name", "name": "Name" },
    {
      "default": "Thanks for your message. I'll get back to you today.",
      "kind": "choice",
      "label": "Answer",
      "name": "Answer",
      "options": ["Thanks for your message. I'll get back to you today.", "Thanks, that works for me."]
    }
  ],
  "folder": "Replies",
  "id": "6F1C2E0A-3B7D-4C1E-9A55-2D8E4F1B7C90",
  "text": "Hi Jordan,\n\nThanks, that works for me.\n\nBest regards,\nAlex Morgan",
  "title": "Quick Reply"
}

The clipboard stays private

{{clipboard}} is never filled in for an AI app. It stays in the text as {{clipboard}}, so the AI can see there's a gap, but not what you copied.

{{tab}} and {{enter}} come back as a tab and a new line, as when you copy a snippet, and {{cursor}} is simply removed.

list_folders

Lists every folder with its id, its full path (like Work ▸ Email) and how many snippets it holds, including those in its subfolders. No parameters.

{
  "folders": [
    { "id": "…", "path": "Replies", "snippets": 12 },
    { "id": "…", "path": "Work ▸ Email", "snippets": 5 }
  ]
}

create_snippet

Saves text as a new snippet.

Parameter	Type	Description
text	text	Required. The snippet's text.
title	text	A short title. Without one, it's named after the first line of the text (up to 60 characters).
folder	text	An existing folder: its path (Work ▸ Email, also written Work > Email or Work/Email), its name if no other folder has the same name, or its id. Without one, the snippet goes into no folder.
placeholders	true/false	Default false: the text pastes exactly as given, so {{something}} stays those characters. Set true only when the text is meant as a template using HandyPaste's own placeholders, such as {{input:Name}} or {{date}}.

Good to know:

• Nothing is saved on a mistake. Empty text or a folder that doesn't exist fails with a message, and no snippet is created.
• It can't create folders. Ask for an existing one, or make the folder in HandyPaste first.
• The free limit doesn't apply, because AI apps need Pro anyway.
• It returns the new snippet (id, title, folder), so the AI can refer to it next.

Try: “Save this as a template in Replies: Hi {{input:Name}}, thanks for your order! Use placeholders.”

update_snippet

Changes an existing snippet. Needs both switches; apps usually ask you to confirm first.

Parameter	Type	Description
id	text	Required. The snippet's id. Titles aren't accepted here, so the AI can't change the wrong snippet by guessing.
title	text	A new title. An empty title names it after the first line of its text.
text	text	New text, replacing all of it. Can't be empty; to remove a snippet, use delete_snippet.
folder	text	Move it to this folder (path, unique name or id). An empty string "" takes it out of its folder.
placeholders	true/false	As in create_snippet, for the new text.

Only the fields given change: the keyword, favorite star and everything else stay as they were. Everything is checked first, so a request with a bad folder or empty text changes nothing. Edits made this way can't be undone with ⌘Z in HandyPaste.

delete_snippet

Moves one snippet, by id, to Recently Deleted. Needs both switches.

Parameter	Type	Description
id	text	Required. The snippet's id.

The result says until when it can be recovered:

{
  "movedToRecentlyDeleted": { "id": "…", "title": "Old signature", "folder": "Archive", "preview": "…" },
  "note": "The user can recover it in HandyPaste ▸ Recently Deleted.",
  "recoverableUntil": "2026-10-25"
}

Recover it any time in the next 30 days from Recently Deleted in the library. See Delete and recover.

Your Prompts folder as prompts

Keep prompts you reuse in a folder named Prompts, or its translation in HandyPaste's language, such as Prompty in Polish. Every snippet in it, and in folders inside it, is offered to AI apps as an MCP prompt: a ready-made message you pick from a menu instead of retyping it.

• Names come from snippet titles, in lower case with hyphens: Proofread Prompt becomes proofread-prompt. Two snippets with the same title become name and name-2.
• Questions become arguments. Each {{input:…}} or {{choose:…}} in the snippet is an argument the app asks you for. It's required unless it has a default answer or is a choice list; choice lists show their options.
• Everything else fills in as in get_snippet: dates, variables, included snippets. {{clipboard}} stays as typed.

For example, a snippet titled Proofread in the Prompts folder:

Proofread this in {{input:Language=English}}. Fix grammar and spelling, keep my tone, and list what you changed:

{{input:Text…}}

becomes the prompt proofread with two arguments: language (optional, default English) and text (required).

Where to find prompts:

• Claude Code: type / and look for /mcp__handypaste__proofread. Arguments follow the command.
• Claude Desktop: look for HandyPaste in the chat box's + menu, where Claude lists what connected servers offer; it asks for the arguments.
• Other apps show MCP prompts in their own way, if they support them.

The prompt list is read when the AI app connects, so after adding a prompt, restart the app, or in Claude Code reconnect with /mcp.

Permissions

Two switches in Settings ▸ AI Apps decide what AI apps may do. Both are off by default.

	Off	Let AI apps use your snippets	+ Allow AI apps to change and delete snippets
Search, read and fill in snippets	–	✓	✓
List folders	–	✓	✓
Use your Prompts folder	–	✓	✓
Create new snippets	–	✓	✓
Rename, edit or move snippets	–	–	✓
Move a snippet to Recently Deleted	–	–	✓

What an AI app can never do, whatever the switches say:

• see your clipboard;
• delete anything for good, empty Recently Deleted, or delete folders;
• change Settings, your variables, keywords or favorites;
• reach snippets while the first switch is off, or without Pro. It only gets a message saying how to turn it on.

update_snippet and delete_snippet are marked as destructive, so apps like Claude ask you to approve each call. Read what the AI is about to change before you approve.

Turning a switch off takes effect immediately, even in a conversation that's already running.

Privacy

HandyPaste's own privacy promises don't change: HandyPaste has no server, no analytics, and connects only to iCloud and the App Store. The connection to AI apps is local, on your Mac.

But snippets an AI app reads go wherever that app sends your conversation, usually its AI service, under that company's privacy policy. So:

• Only turn on AI apps if you're comfortable sharing your snippets with the AI service you use.
• Snippets are shared only when the AI asks for them: a search shares titles and the first 160 characters of the matches, and a snippet's full text is only shared when it's requested.
• Keep anything you'd never paste into a chat, like passwords, out of HandyPaste. It isn't a password manager.

Free and Pro

Connecting AI apps is part of HandyPaste Pro. On the free version, the AI Apps tab offers Unlock Pro…, and an AI app that's already configured gets a message that the feature needs Pro, without seeing any snippets.

Troubleshooting

“HandyPaste isn't sharing snippets with AI apps.” Turn on Settings ▸ AI Apps ▸ Let AI apps use your snippets. It works right away; no restart needed.

“Connecting AI apps is part of HandyPaste Pro.” Unlock Pro, or restore it with Restore Purchases in the Pro window. See Free and Pro.

“HandyPaste doesn't let AI apps change or delete snippets.” The AI tried to edit or delete. If you want that, turn on Allow AI apps to change and delete snippets.

“HandyPaste isn't running and couldn't be opened.” The relay couldn't start HandyPaste within 20 seconds. Open HandyPaste yourself, then try again. If it keeps happening, check that the path in your configuration still points to HandyPaste. Copy it again from Settings ▸ AI Apps after moving the app.

HandyPaste doesn't appear in Claude at all.

• Claude Desktop: make sure the configuration is valid JSON (commas between entries, matching braces) and that you quit and reopened Claude. Claude's Developer settings show whether the server started and its error.
• Claude Code: run claude mcp list. If handypaste is missing, run the command again; if it's failing, /mcp shows why.

New snippets in Prompts don't show up. Apps load the prompt list when they connect. Restart the app, or reconnect with /mcp in Claude Code.

The AI says a snippet asks for something. That's a question without a default, like {{input:Name}}. Tell it the answer, and it fills the snippet in.

Detailed logs for a bug report. Add the environment variable HANDYPASTE_MCP_DEBUG=1 to HandyPaste's entry, and the relay reports how it connects to HandyPaste on standard error, which the AI app keeps in its logs (Claude Desktop: the mcp-server-handypaste log in ~/Library/Logs/Claude/). HandyPaste itself logs problems starting its side under the mcp category in the Console app. In Claude Desktop's configuration:

"handypaste": {
  "args": ["--mcp"],
  "command": "/Applications/HandyPaste.app/Contents/MacOS/HandyPaste",
  "env": { "HANDYPASTE_MCP_DEBUG": "1" }
}

In Claude Code, add -e HANDYPASTE_MCP_DEBUG=1 after --scope user in the claude mcp add command. Include the log when you contact support.

Technical reference

For developers connecting their own MCP client.

Transport	stdio: newline-delimited JSON-RPC 2.0, one message per line (up to 4 MB)
Command	<HandyPaste.app>/Contents/MacOS/HandyPaste --mcp
Protocol versions	2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. The client's version is used when supported, otherwise the newest.
Server info	name handypaste, title HandyPaste, version = the app's version
Capabilities	tools and prompts, both with listChanged: false
Methods	initialize, ping, tools/list, tools/call, prompts/list, prompts/get; notifications get no reply
Not supported	batches (error -32600), resources, sampling
Errors	protocol problems use JSON-RPC codes (-32700 parse, -32600 invalid request, -32601 unknown method, -32602 unknown tool or bad prompt arguments). A tool that can't do what was asked returns a normal result with isError: true and a message the model can act on.
Tool annotations	readOnlyHint on search, get and list; destructiveHint on update and delete; openWorldHint: false on all
Limits	search_snippets returns at most 50 results; a snippet holds up to 200,000 characters; included snippets nest up to 8 levels

The server also sends short instructions at initialization, telling the model to search the library before writing text the user may already have saved.