HandyPaste

Aplicativos de IA (MCP)

O HandyPaste pode compartilhar sua biblioteca de trechos com o Claude e outros aplicativos de IA que suportam o Model Context Protocol (MCP). Uma vez conectado, você pode pedir à IA para encontrar um trecho, preenchê-lo ou salvar algo que ela escreveu como um novo trecho, e os trechos na sua pasta Prompts se tornam prompts prontos. Esta página é a configuração completa e referência; para uma visão rápida, veja seus trechos no Claude.

Nada é compartilhado até você ativar, um aplicativo de IA nunca vê sua área de transferência e não pode excluir nada permanentemente.

O que você pode pedir

Algumas coisas que funcionam quando o HandyPaste está conectado:

• "Encontre minha resposta de atraso de envio e preencha para Jordan, pedido 48213."
• "Qual é o meu endereço do escritório? Use-o neste e-mail."
• "Salve essa resposta como um trecho em Respostas chamado Reembolso aprovado."
• "Transforme esta mensagem em um modelo que pergunta o nome do cliente e salve-o."
• "Quais dos meus trechos mencionam a política de reembolso?"
• "Mova minha assinatura antiga para Arquivo e renomeie para Assinatura antiga" (precisa do segundo interruptor, veja abaixo).

A IA decide qual ferramenta do HandyPaste usar. Você verá cada chamada no chat, e a maioria dos aplicativos pede confirmação antes de executar.

Configuração

Você precisa do HandyPaste Pro e do HandyPaste instalado no Mac onde o aplicativo de IA é executado.

1. Ative no HandyPaste

1. Abra HandyPaste ▸ Configurações… (⌘,) e escolha a aba Aplicativos de IA.
2. Ative Permitir que aplicativos de IA usem seus trechos.
3. Deixe Permitir que aplicativos de IA alterem e excluam trechos desativado, a menos que você queira que a IA edite ou remova trechos existentes. O que cada interruptor permite.

A aba Aplicativos de IA também tem o texto exato que cada aplicativo precisa, com a localização real do HandyPaste no seu Mac preenchida. Use os botões dela em vez de digitar os caminhos abaixo.

2a. Conecte o Claude Desktop

1. Em HandyPaste ▸ Configurações ▸ Aplicativos de IA, clique em Copiar Configuração ao lado de Claude Desktop.
2. No Claude, escolha Configurações ▸ Desenvolvedor ▸ Editar Configuração. O Finder mostra o arquivo claude_desktop_config.json; abra-o em um editor de texto.
3. Cole a configuração:
   • Se o arquivo estiver vazio ou contiver apenas {}, substitua tudo pelo que você copiou.
     • Se já tiver uma seção "mcpServers", adicione apenas a entrada "handypaste" dentro dela, com uma vírgula após a entrada anterior.
4. Salve o arquivo e saia e reabra o Claude (⌘ Q, não apenas feche a janela).

O que você cola se parece com isto, com o caminho para sua cópia do HandyPaste:

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

E mesclado com outro servidor que você já tinha:

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

Após reiniciar, o HandyPaste aparece entre as ferramentas conectadas do Claude. Tente: "Pesquise meus trechos do HandyPaste por endereço."

2b. Conecte o Claude Code

1. Em HandyPaste ▸ Configurações ▸ Aplicativos de IA, clique em Copiar Comando ao lado de Claude Code.
2. Cole no Terminal e pressione Return.

Fica assim:

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

--scope user torna o HandyPaste disponível em todos os projetos. Verifique com claude mcp list, ou digite /mcp dentro do Claude Code para ver o status e as ferramentas. Para remover depois: claude mcp remove --scope user handypaste.

2c. Outros aplicativos MCP

Qualquer aplicativo que possa iniciar um servidor MCP local (stdio) funciona. Ele precisa de duas coisas:

Configuração	Valor
Comando	/Applications/HandyPaste.app/Contents/MacOS/HandyPaste (o caminho da sua cópia)
Argumentos	--mcp

Muitos aplicativos usam o mesmo formato mcpServers do Claude Desktop, então a configuração copiada geralmente funciona como está. Verifique a documentação do seu aplicativo para saber onde ficam as configurações de MCP.

Se você mover o HandyPaste

A configuração aponta para a localização do HandyPaste. Se você mover o aplicativo, por exemplo, de Downloads para Aplicativos, copie a configuração ou o comando novamente e substitua o antigo.

3. Verifique se funciona

Pergunte ao aplicativo de IA algo como "Liste minhas pastas do HandyPaste." Se ele responder com suas pastas, está pronto. Se disser que o HandyPaste não está compartilhando trechos, ou que faz parte do Pro, veja Solução de problemas.

Como funciona

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

• O aplicativo de IA inicia HandyPaste --mcp, o mesmo aplicativo HandyPaste em modo de retransmissão. Ele não abre janela e não lê sua biblioteca diretamente.
• A retransmissão passa mensagens para o HandyPaste em execução por uma conexão privada dentro do sandbox do HandyPaste, que apenas sua conta de usuário pode abrir.
• Se o HandyPaste não estiver em execução, a retransmissão o inicia silenciosamente, sem janelas, assim como quando abre no login, e espera até 20 segundos para que fique pronto.
• Cada pesquisa e alteração acontece no HandyPaste, pelo mesmo código da janela da biblioteca. As alterações sincronizam com seus outros Macs, aparecem no seletor imediatamente, e trechos movidos para Excluídos Recentemente podem ser recuperados normalmente.
• O próprio HandyPaste não se conecta a nada novo. A retransmissão é local. Mas tudo o que o aplicativo de IA lê é enviado ao serviço de IA desse aplicativo, como qualquer outra coisa que você compartilha em um chat. Veja Privacidade.

Ferramentas

Estas são as ferramentas que o HandyPaste oferece. Você não as chama diretamente; a IA faz isso, com base no que você pede. Conhecê-las ajuda a formular solicitações e entender o que você vê no chat.

Ferramenta	O que faz	Altera sua biblioteca?	Necessita
search_snippets	Encontra trechos por título, palavra-chave e texto	Não	Primeiro interruptor
get_snippet	Retorna um trecho, preenchido como uma colagem	Não	Primeiro interruptor
list_folders	Lista suas pastas	Não	Primeiro interruptor
create_snippet	Salva um novo trecho	Adiciona um	Primeiro interruptor
update_snippet	Altera o título, texto ou pasta de um trecho	Sim	Ambos os interruptores
delete_snippet	Move um trecho para Excluídos Recentemente	Sim	Ambos os interruptores

Todos os resultados voltam como texto JSON que a IA lê. Os trechos são identificados por um id (um UUID) que search_snippets retorna.

search_snippets

Pesquisa seus trechos da mesma forma que o seletor: por título, palavra-chave e texto, ignorando maiúsculas e acentos, melhor correspondência primeiro.

Parâmetro	Tipo	Descrição
query	texto	Palavras para procurar. Vazio lista seus trechos: favoritos primeiro, depois usados recentemente, depois por título.
limit	número	Quantos resultados, 1–50. Padrão 20.

Retorna o id de cada trecho, título, pasta, palavra-chave, se é favorito e os primeiros 160 caracteres do texto, além do número total de correspondências:

{
  "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

Retorna o texto de um trecho, preenchido como se você tivesse colado: datas e horários, suas variáveis e trechos incluídos.

Parâmetro	Tipo	Descrição
id	texto	O id do trecho, de search_snippets.
title	texto	Ou o título exato (ignorando maiúsculas), se não houver id. Com títulos duplicados, o mais antigo é usado, como com {{snippet:…}}.
fill	verdadeiro/falso	Preenche espaços reservados. Padrão true. Com false, retorna o texto como o editor mostra, espaços reservados e tudo.
answers	objeto	Respostas às perguntas do trecho, por nome de campo, ex. {"Name": "Jordan"}.

As perguntas funcionam como no seletor:

• Uma pergunta com resposta padrão e lista de escolhas (sua primeira escolha) é preenchida automaticamente, a menos que answers diga o contrário.
• Uma pergunta com nenhum dos dois faz a chamada falhar com uma mensagem nomeando os campos, por exemplo: "Quick Reply" pergunta por "Nome". Pergunte ao usuário e chame get_snippet novamente com respostas. A IA então pergunta a você e tenta novamente.
• O resultado lista cada pergunta sob fields, com nome, tipo (text, multiline text ou choice), opções e padrão.

{
  "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"
}

A área de transferência permanece privada

{{clipboard}} nunca é preenchido para um aplicativo de IA. Ele permanece no texto como {{clipboard}}, para que a IA veja que há uma lacuna, mas não o que você copiou.

{{tab}} e {{enter}} voltam como uma tabulação e uma nova linha, como quando você copia um trecho, e {{cursor}} é simplesmente removido.

list_folders

Lista cada pasta com seu id, caminho completo (como Work ▸ Email) e quantos trechos contém, incluindo os de subpastas. Sem parâmetros.

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

create_snippet

Salva texto como um novo trecho.

Parâmetro	Tipo	Descrição
text	texto	Obrigatório. O texto do trecho.
title	texto	Um título curto. Sem um, é nomeado pela primeira linha do texto (até 60 caracteres).
folder	texto	Uma pasta existente: seu caminho (Work ▸ Email, também escrito Work > Email ou Work/Email), seu nome se nenhuma outra pasta tiver o mesmo nome, ou seu id. Sem um, o trecho vai para nenhuma pasta.
placeholders	verdadeiro/falso	Padrão false: o texto cola exatamente como dado, então {{something}} permanece esses caracteres. Defina true apenas quando o texto for destinado a ser um modelo usando os próprios espaços reservados do HandyPaste, como {{input:Name}} ou {{date}}.

Bom saber:

• Nada é salvo em caso de erro. Texto vazio ou pasta inexistente falha com uma mensagem, e nenhum trecho é criado.
• Não pode criar pastas. Peça uma existente ou crie a pasta no HandyPaste primeiro.
• O limite gratuito não se aplica, porque aplicativos de IA precisam do Pro de qualquer forma.
• Retorna o novo trecho (id, título, pasta), para que a IA possa se referir a ele depois.

Tente: "Salve isto como um modelo em Respostas: Olá {{input:Nome}}, obrigado pelo seu pedido! Use espaços reservados."

update_snippet

Altera um trecho existente. Precisa de ambos os interruptores; aplicativos geralmente pedem confirmação primeiro.

Parâmetro	Tipo	Descrição
id	texto	Obrigatório. O id do trecho. Títulos não são aceitos aqui, para que a IA não altere o trecho errado por adivinhação.
title	texto	Um novo título. Um título vazio o nomeia pela primeira linha do texto.
text	texto	Novo texto, substituindo tudo. Não pode ser vazio; para remover um trecho, use delete_snippet.
folder	texto	Move para esta pasta (caminho, nome único ou id). Uma string vazia "" o tira da pasta.
placeholders	verdadeiro/falso	Como em create_snippet, para o novo texto.

Apenas os campos fornecidos mudam: a palavra-chave, estrela de favorito e todo o resto permanecem como estavam. Tudo é verificado primeiro, então uma solicitação com pasta inválida ou texto vazio não muda nada. Edições feitas desta forma não podem ser desfeitas com ⌘ Z no HandyPaste.

delete_snippet

Move um trecho, por id, para Excluídos Recentemente. Precisa de ambos os interruptores.

Parâmetro	Tipo	Descrição
id	texto	Obrigatório. O id do trecho.

O resultado diz até quando pode ser recuperado:

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

Recupere-o a qualquer momento nos próximos 30 dias em Excluídos Recentemente na biblioteca. Veja Excluir e recuperar.

Sua pasta Prompts como prompts

Mantenha prompts que você reutiliza em uma pasta chamada Prompts, ou sua tradução no idioma do HandyPaste, como Prompty em polonês. Cada trecho nela, e em pastas dentro dela, é oferecido a aplicativos de IA como um prompt MCP: uma mensagem pronta que você escolhe em um menu em vez de redigitar.

• Nomes vêm dos títulos dos snippets, em minúsculas com hífens: Proofread Prompt vira proofread-prompt. Dois snippets com o mesmo título viram name e name-2.
• Perguntas viram argumentos. Cada {{input:…}} ou {{choose:…}} no snippet é um argumento que o app pede para você. É obrigatório a menos que tenha uma resposta padrão ou seja uma lista de opções; listas de opções mostram suas alternativas.
• Todo o resto é preenchido como em get_snippet: datas, variáveis, snippets incluídos. {{clipboard}} permanece como digitado.

Por exemplo, um snippet intitulado Proofread na pasta Prompts:

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

{{input:Text…}}

vira o prompt proofread com dois argumentos: language (opcional, padrão inglês) e text (obrigatório).

Onde encontrar os prompts:

• Claude Code: digite / e procure por /mcp__handypaste__proofread. Os argumentos vêm depois do comando.
• Claude Desktop: procure por HandyPaste no menu + da caixa de chat, onde o Claude lista o que os servidores conectados oferecem; ele pede os argumentos.
• Outros apps mostram os prompts do MCP do seu próprio jeito, se forem compatíveis.

A lista de prompts é lida quando o app de IA conecta, então depois de adicionar um prompt, reinicie o app, ou no Claude Code reconecte com /mcp.

Permissões

Dois interruptores em Configurações ▸ Apps de IA decidem o que os apps de IA podem fazer. Ambos estão desligados por padrão.

	Desligado	Deixar apps de IA usarem seus snippets	+ Permitir que apps de IA alterem e excluam snippets
Buscar, ler e preencher snippets	–	✓	✓
Listar pastas	–	✓	✓
Usar sua pasta Prompts	–	✓	✓
Criar novos snippets	–	✓	✓
Renomear, editar ou mover snippets	–	–	✓
Mover um snippet para Excluídos Recentemente	–	–	✓

O que um app de IA nunca pode fazer, não importa o que os interruptores digam:

• ver sua área de transferência;
• excluir algo permanentemente, esvaziar Excluídos Recentemente ou excluir pastas;
• alterar Configurações, suas variáveis, palavras-chave ou favoritos;
• acessar snippets enquanto o primeiro interruptor estiver desligado, ou sem o Pro. Ele só recebe uma mensagem dizendo como ativar.

update_snippet e delete_snippet são marcados como destrutivos, então apps como o Claude pedem que você aprove cada chamada. Leia o que a IA está prestes a alterar antes de aprovar.

Desligar um interruptor tem efeito imediato, mesmo em uma conversa já em andamento.

Privacidade

As promessas de privacidade do HandyPaste não mudam: o HandyPaste não tem servidor, não tem analytics e conecta apenas ao iCloud e à App Store. A conexão com apps de IA é local, no seu Mac.

Mas snippets que um app de IA lê vão para onde esse app enviar sua conversa, geralmente o serviço de IA dele, sob a política de privacidade dessa empresa. Então:

• Só ative os apps de IA se você se sentir confortável em compartilhar seus snippets com o serviço de IA que usa.
• Snippets são compartilhados apenas quando a IA pede: uma busca compartilha títulos e os primeiros 160 caracteres dos resultados, e o texto completo de um snippet só é compartilhado quando é solicitado.
• Mantenha qualquer coisa que você nunca colaria num chat, como senhas, fora do HandyPaste. Ele não é um gerenciador de senhas.

Grátis e Pro

Conectar apps de IA faz parte do HandyPaste Pro. Na versão gratuita, a aba Apps de IA oferece Desbloquear Pro…, e um app de IA já configurado recebe uma mensagem de que o recurso precisa do Pro, sem ver nenhum snippet.

Solução de problemas

“O HandyPaste não está compartilhando snippets com apps de IA.” Ative Configurações ▸ Apps de IA ▸ Deixar apps de IA usarem seus snippets. Funciona na hora; não precisa reiniciar.

“Conectar apps de IA faz parte do HandyPaste Pro.” Desbloqueie o Pro, ou restaure com Restaurar Compras na janela do Pro. Veja Grátis e Pro.

“O HandyPaste não deixa apps de IA alterarem ou excluírem snippets.” A IA tentou editar ou excluir. Se você quiser isso, ative Permitir que apps de IA alterem e excluam snippets.

“O HandyPaste não está rodando e não pôde ser aberto.” O relay não conseguiu abrir o HandyPaste em 20 segundos. Abra o HandyPaste você mesmo e tente de novo. Se continuar acontecendo, verifique se o caminho na sua configuração ainda aponta para o HandyPaste. Copie de novo em Configurações ▸ Apps de IA depois de mover o app.

O HandyPaste não aparece no Claude de jeito nenhum.

• Claude Desktop: confirme que a configuração é JSON válido (vírgulas entre entradas, chaves correspondentes) e que você saiu e reabriu o Claude. As configurações de Developer do Claude mostram se o servidor iniciou e o erro dele.
• Claude Code: execute claude mcp list. Se handypaste estiver faltando, execute o comando de novo; se estiver falhando, /mcp mostra o motivo.

Novos snippets em Prompts não aparecem. Os apps carregam a lista de prompts quando conectam. Reinicie o app, ou reconecte com /mcp no Claude Code.

A IA diz que um snippet pede algo. Isso é uma pergunta sem padrão, como {{input:Name}}. Diga a resposta, e ela preenche o snippet.

Logs detalhados para um relatório de bug. Adicione a variável de ambiente HANDYPASTE_MCP_DEBUG=1 à entrada do HandyPaste, e o relay reporta como conecta ao HandyPaste na saída de erro padrão, que o app de IA mantém nos logs (Claude Desktop: o log mcp-server-handypaste em ~/Library/Logs/Claude/). O próprio HandyPaste registra problemas ao iniciar o lado dele na categoria mcp no app Console. Na configuração do Claude Desktop:

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

No Claude Code, adicione -e HANDYPASTE_MCP_DEBUG=1 depois de --scope user no comando claude mcp add. Inclua o log quando entrar em contato com o suporte.

Referência técnica

Para desenvolvedores conectando seu próprio cliente MCP.

Transporte	stdio: JSON-RPC 2.0 delimitado por nova linha, uma mensagem por linha (até 4 MB)
Comando	<HandyPaste.app>/Contents/MacOS/HandyPaste --mcp
Versões de protocolo	2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. A versão do cliente é usada quando suportada, caso contrário, a mais recente.
Informações do servidor	nome handypaste, título HandyPaste, versão = versão do app
Capacidades	tools e prompts, ambos com listChanged: false
Métodos	initialize, ping, tools/list, tools/call, prompts/list, prompts/get; notificações não recebem resposta
Não suportado	lotes (erro -32600), recursos, amostragem
Erros	problemas de protocolo usam códigos JSON-RPC (-32700 parse, -32600 solicitação inválida, -32601 método desconhecido, -32602 ferramenta desconhecida ou argumentos de prompt ruins). Uma ferramenta que não consegue fazer o que foi pedido retorna um resultado normal com isError: true e uma mensagem na qual o modelo pode agir.
Anotações de ferramentas	readOnlyHint em busca, obter e listar; destructiveHint em atualizar e excluir; openWorldHint: false em todos
Limites	search_snippets retorna no máximo 50 resultados; um snippet comporta até 200.000 caracteres; snippets incluídos aninham até 8 níveis

O servidor também envia um breve instructions na inicialização, dizendo ao modelo para buscar na biblioteca antes de escrever texto que o usuário talvez já tenha salvo.