Reference
Agent access
Last updated November 10, 2026
Grain has a local MCP server and a command-line tool built in, so an assistant on your Mac, such as Claude or ChatGPT, can search your whole library, read what was said and look at the previews you allow. It works from your real archive, and you keep the creative calls.
It can read
- Search by what's in a photo or video, and by text
- Search spoken dialogue and read timed transcripts
- See previews, read metadata
- Find similar media
It can write, to the catalog
- Add media to collections
- Edit catalog metadata such as captions and tags
- Write a timed visual description of a video
It leaves to you
- Adding clips: it proposes selects with timecodes
- Your originals and sidecars: never changed
- Adding new folders and drives
An agent with your library
Most assistants only know what you paste into the chat. Connected to Grain, an assistant can do the fetching itself: run twenty searches across ten years of shoots, read the transcripts of every interview, look at the frames it's allowed to see, and come back with a shortlist and its reasons.
Grain offers its tools through MCP, the standard way an assistant uses another app. The assistant decides which tool a request needs and works with what comes back. It can only do what those tools allow. What is MCP? explains it in plain terms.
The connection is local. Grain must be open, and the assistant must run on the same Mac: Claude Desktop, the ChatGPT desktop app, or an agent or script you run yourself.
Proposes, then you choose
An agent is good at the reading: every transcript, every caption, every frame in a long search. You're better at the choosing. Grain's tools are built around that split.
For video, the agent searches dialogue across a source, reads timed transcripts and proposes selects with recordings and timecodes. You play each pick in Grain and choose Add Clip on the ones that hold up. For photos, it can gather candidates into a collection and write captions or tags into the catalog, and you review the set before it goes anywhere.
Beyond Grain, an agent with file access to your exported clips can string them into a rough cut, make vertical versions, burn in captions or write an edit decision list, using ffmpeg or similar tools. That's the agent's work with other tools, and you review what it makes. See agentic video editing.
Choose what it can reach
Every switch lives in Settings → Connectors → MCP, and nothing is reachable until you turn on Allow local tools.
| Switch | What it allows |
|---|---|
| Allow local tools | Catalog search, metadata edits and collection changes |
| Allow tools to read previews | Looking at images, to compare light, framing and continuity |
| Allow tools to read original file bytes | Reading the original files themselves |
| Allow tools to manage existing sources | Enabling, disabling or rescanning sources you've already added |
Without preview access, an agent still works from search results and recorded metadata. New folders and Dropbox sign-in always go through Settings → Sources, in Grain.
What leaves your Mac
Grain's own analysis runs on your Mac: visual search, transcription and faces. Connecting an assistant adds a second step with its own sharing. Whatever the assistant reads, such as filenames, metadata, transcripts and the previews it views, goes to that assistant's provider and is handled under its policies.
Stays on your Mac
- Your originals, on your drives
- Grain's catalog and its analysis
- Anything the agent doesn't ask for
Goes to the assistant's provider
- The results of each tool it calls
- Transcripts and metadata it reads
- Previews and originals, if you allow them
For client or NDA work, keep requests to the sources you're comfortable sharing, or leave previews off. Media privacy and archive reliability goes through the trade-offs, and how Grain handles your files covers what's stored where.
Set it up
- Open Grain and keep it running.
- Open Settings → Connectors → MCP and turn on Allow local tools.
- Choose Copy Configuration and add it to your assistant. The Claude and ChatGPT guides walk through each one.
- Start with a read-only request, such as listing your sources, before you ask for any edits.
For scripts and local agents, Settings → Connectors → CLI has Copy Command. It lists your sources; replace sources --json with tools --json to see every command and its inputs.
For example conversations, from a brief to a finished collection, see AI workflows with your own library.
Every control, at a glance
- Private, on-device analysis
- Search your archive without sending it to a cloud search service. Grain’s built-in visual analysis and search run on your Mac. Connecting a separate assistant is an additional workflow with its own sharing choices.
- Built-in MCP server
- Let a compatible assistant search and inspect your catalog. Connect an assistant to Grain’s local MCP tools on the same Mac. The tools expose catalog search, metadata, previews, and supported catalog actions.
- Bundled command-line tool
- Bring the library into scripts and agent workflows. Use Grain’s installed CLI from a local tool-capable agent or script. Follow the setup guide for the installed app and connection requirements.
- Skills and setup instructions
- Give an agent a repeatable way to work with the library. Pair the connection with Grain’s instructions or an available skill so the agent can discover, search, inspect, and use selected media.
- Previews for your assistant
- Let the assistant assess the actual photographs. A connected assistant can inspect allowed previews and use recorded metadata to compare candidates. Data you share is handled under that assistant provider’s policies.
- Creative workflows beyond search
- Build toward a pitch, portfolio, or edit using your own work. Grain supplies the searchable media and context. Your agent combines it with the other tools you connect to make the deliverable; editing and publishing depend on those tools.