Search Mac Clipboard History with an AI Agent via MCP

You copied an error message, then copied something else. To give that earlier error to your AI agent, you can search Paste It!'s saved history through MCP instead of finding and copying it again.

The setup: run Paste It! on your Mac, enable MCP, and connect an agent that supports HTTP MCP to http://127.0.0.1:17321/mcp. The agent must be able to reach that Mac's local endpoint.

Version and disclosure: we make Paste It!. This guide covers 0.2.9, released September 28, 2026. The current download includes the MCP reconnect fix and improved OCR. The text and image examples below were checked on the released Apple Silicon build.

1. Enable MCP in Paste It!

Open Paste It!, right-click its menu bar icon, and enable MCP. It is off by default. Enabling it copies the URL; Copy MCP URL copies it again while the server is on.

http://127.0.0.1:17321/mcp

Keep the app running. There is no separate clipboard server to install. Opening this URL in a browser returns 405 Method Not Allowed, because the endpoint expects MCP POST requests.

2. Connect your agent

In your agent's MCP configuration, add a Streamable HTTP server with the URL above. Paste It! does not require a token or OAuth login. A cloud-only agent cannot reach your Mac through its own 127.0.0.1.

For example, if you use Codex CLI, add the server with:

codex mcp add paste-it --url http://127.0.0.1:17321/mcp

Or add the following entry to ~/.codex/config.toml, preserving existing settings:

[mcp_servers.paste-it]
url = "http://127.0.0.1:17321/mcp"

These are alternative setup methods. OpenAI documents HTTP server configuration in its MCP guide. Other agents use different configuration formats; give them the same URL and HTTP transport.

Check that the server's tools are available, then ask:

Call paste_it_health. Tell me whether the app is running, without reading clipboard items.

The response should report ok: true and running: true. Our release test returned version: "0.2.9".

3. Find something you copied earlier

Start with a harmless sample. Copy this marker, wait for it to appear in Paste It!, and then copy a different phrase such as green notebook:

paste-it-agent-check-20260928-R9

Ask your agent:

Use paste_it_search to find paste-it-agent-check-20260928-R9, with type text and limit 3. Return only the matching text.

The tool arguments are:

{
  "q": "paste-it-agent-check-20260928-R9",
  "type": "text",
  "limit": 3
}

In our September 28 test, this query had zero results before capture and one result after capture. After different content replaced the clipboard, the same saved item was still returned. Here is an excerpt from that actual response, with the ID and other metadata omitted:

{
  "query": "paste-it-agent-check-20260928-R9",
  "total": 1,
  "clips": [
    {
      "primaryType": "text",
      "plainText": "paste-it-agent-check-20260928-R9"
    }
  ]
}

For everyday use, replace the marker with a distinctive fragment of the error or URL you remember. Search only the history needed for the task. An agent cannot recover something Paste It! never captured or has already removed under its retention settings.

4. Find a copied image by the words inside it

An image must first be captured and have OCR text available. For a reproducible example, we used this synthetic image:

The input image from our test, not a screenshot of an agent interface. Open full-size PNG.

After copying the PNG and then replacing the clipboard, we called paste_it_search with:

{
  "q": "RELEASE928R9 RAVEN",
  "type": "image",
  "limit": 5
}

It returned one image with empty plainText and this ocrText:

RAVEN 4821 RELEASE928R9
Invoice pending
Total USD 123.45

That distinguishes an OCR match from a matching ordinary text clip. We then passed the returned image ID to paste_it_get_clip with includeBlobs: true; the recovered PNG was byte-for-byte identical to the input. A Chinese image was also found by 星河 and retrieved intact after a second copy; the first copy had not produced a match during the wait window. See the OCR walkthrough for the sample and recognition limits.

For your own image, ask the agent to search for a distinctive word with type image, then retrieve only the matching ID. Leave includeBlobs off if you only need its text; enable it when you need the original image data.

If the connection or search fails

For manual connection diagnostics and the complete tool schemas, see the MCP documentation.

What your agent can access

While MCP is on, local software that can reach the port can call the tools; there is no per-client password. Search and list responses contain saved text, OCR and metadata. Your AI client may send those results or retrieved images to its model provider, even though Paste It!'s server runs locally. Use narrow queries, review your client's data settings, and turn MCP off when finished.

The history tools do not insert, delete or clear your main history. The separate paste_it_render_screenshot tool creates temporary UI and an output file; it is not needed for searching. Excluding an app from future capture does not remove its existing history.

How we checked this

On September 28, 2026, Codex carried out the sample workflow through a local HTTP helper sending MCP requests to the installed Paste It! 0.2.9 / build 11 app. Synthetic text and two PNGs were written through the macOS pasteboard API. We checked for zero matching items first, then verified text/image searches after replacing the clipboard and compared the retrieved PNGs with their inputs. This tested the agent-driven MCP workflow; it did not test Codex's saved-server configuration or its settings UI.

The installed app passed signature verification, and its executable and code-signing hash matched the official 0.2.9 Apple Silicon DMG. The fixes are included in the release source. The same day's connection regression checks passed two independent clients, reconnects, and 24 concurrent clients reusing request IDs. These checks do not measure productivity gains or compare competing apps.