Using MCP

Every Poly integration — Claude, ChatGPT, Gemini, your editor — ends up talking to the same three tools. Knowing what they do makes it much easier to steer an agent and to debug it when something goes sideways.

The three tools

search

Free-text search across all your files. Results come back ranked in two groups — full-text matches (the words literally appear) and semantic matches (the meaning matches) — with each file's name, path, location, a highlighted snippet, and links to open it. It's the same engine behind Poly's own search.

fetch

Returns the contents of a single file. What "contents" means depends on the file: text files and documents return text (PDFs return their extracted text), audio and video return a transcript, and images return the image itself. Agents typically call search first and fetch the interesting results.

cli

A virtual poly command line for everything else — browsing (ls), organizing (mv, mkdir, file update), writing (file write, wget), and history (file history, file restore). The agent passes arguments exactly as you would type them, and can run --help on anything to discover commands. A few differences from the desktop CLI: only Poly refs work (no local filesystem paths), there's no working directory, and content for file write is passed with --text.

Irreversible actions are blocked over MCP: rm archives files (reversible), and permanently deleting from the Archive is reserved for you, in your own terminal.

Troubleshooting

Ask what it ran. The cli tool takes the same commands the desktop CLI does, so when an agent gets a confusing result, ask it "what CLI command did you just run?" — then run the command yourself:

poly ls //Home/projects --output json

If it fails for you too, the issue is the command (a wrong path, a stale ref); if it works for you, the agent likely misread the output, so paste yours back and let it retry.

Change how files are referenced. Poly accepts several spellings of the same file — a //Home/… path, a web URL, a polyapp:// deep link. Names with special characters (quotes, slashes) occasionally trip an agent up; asking it to "use the file's link instead of its path" (or vice versa) usually resolves it, since IDs sidestep naming entirely.

Check what the file looks like to Poly. If an agent says a file is empty or unreadable, run poly file show on it yourself — a file that hasn't finished indexing has no extracted text yet, and --wait-for-indexing on the write is the fix for pipelines that read right after writing.

Missing results usually mean scope. The hosted MCP server searches everything you can access, but an agent may be filtering — ask it to search --under //Home or to drop filters and retry.