# Using MCP

> The three Poly MCP tools — cli, search, and fetch — and how to troubleshoot agent behavior.

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](/searching).

### `fetch`

Returns the contents of a single file. What "contents" means depends on the file: text files and documents return text ([PDFs](/mime-types/application/pdf) 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](/cli/commands) for everything else — browsing (`ls`), organizing (`mv`, `mkdir`, `file update`), writing (`file write`, `wget`), and history ([`file history`](/cli/commands/file-history), [`file restore`](/cli/commands/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](/cli) does, so when an agent gets a confusing result, ask it *"what CLI command did you just run?"* — then run the command yourself:

```bash
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`](/cli/commands/file-show) on it yourself — a file that hasn't finished [indexing](/searching) 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.