Skip to content

Agents (MCP)

Kist has a Model Context Protocol endpoint built in: streamable HTTP at /mcp, with the same bearer tokens as the API. An agent can search your library, see the images (view_item hands the model the picture itself), add things, tag them and file them. Whatever it does is one batch in Recent changes, so one undo reverts it, and there is deliberately no tool that deletes anything for good.

Connect Claude Code

claude mcp add --transport http kist https://kist.example.com/mcp \
  --header "Authorization: Bearer <token>"

The first-run checklist in the web app shows this command with your server's address filled in. For Claude Desktop and other MCP clients, add a remote (streamable HTTP) server with that URL and an Authorization: Bearer header.

Give agents their own token with the agent scope (below), so the history shows what the agent did under its name and you can revoke it on its own.

Things to ask

  • "Find the navy blazer photos I saved and file them into Menswear."
  • "What did I save last week about kitchen lighting? Show me the best three."
  • "Tag everything in Unfiled that's a screenshot of a receipt with receipts."
  • "Make a moodboard from my picks in the Interiors folder, as a masonry grid."
  • "Undo the filing you just did."

The server tells agents to pass your description of what something looks like as a meaning search, so "moody dark interiors" works without Kist running a language model of its own.

Tools

tool
search_items words, tags, folder, type, rating, flags, labels, people, dates, camera, place …; ranked by meaning (semantic), similar_to, color or text inside images
search_by_image items that look like an image given by URL or a file under library/import/ (nothing is saved)
view_item, get_item, item_palette see the image, read its metadata, its colours
nearest_colour_code, list_colour_books the nearest code in your colour books to a hex or an item's colours; the books and their swatches
list_kinds, correct_kind the kinds (Screenshots, Drawings, Low-res …) and correcting them; search_items(auto_kind=…) lists a kind
add_item from a URL, or a file under library/import/ or library/inbox/
update_item, set_tags, set_folders, set_provenance organise: caption, flag, label, rating, protect, folders, credit and licence
set_credits, item_credits, credits_clearance, print_check credits and rights in bulk, auto-fill from the item's own files, what isn't cleared before a share, print size and colour profile
list_folders, create_folder, list_tags, list_smart_folders, get_vocabulary browse; read the vocabulary before tagging
suggest_tags, tag_cleanup, merge_tags tag suggestions with reasons; cleanup as one undoable batch (dry_run first)
duplicate_groups, resolve_duplicates, suggest_stacks, stack_items tidy duplicates and stacks
list_boards, get_board, create_board, add_to_board, annotate moodboards and pinned notes
list_shows, create_show saved Present shows: a folder, smart folder, board or chosen items as a full-screen show, with compare pairs; open one at its web_url
cut_out_subject the subject as a new transparent item (a job on your ml service; the original is untouched)
view_video, save_frame, make_clip watch a video as a contact sheet, keep a frame, cut a clip
export_collection, export_status, get_page_snapshot portable exports, the saved text of a source page
list_projects, get_project, set_field_values projects and their custom fields; set field values on items; search_items(project=…, fields={...})
guest_feedback, accept_guest_feedback picks, hearts and comments guests left on share links; accept them as picks, labels or notes (one undoable batch)
recent_batches, undo_batch what changed lately, by whom, and undo it
trash_item, restore_item into and out of the trash (emptying it is a human action in the web app)

The README lists every tool with every parameter.

Tokens

KIST_TOKEN is the owner's token (scope admin). Make narrower named tokens in Settings → Tokens (or POST /api/tokens); the token is shown once, and only its SHA-256 is stored.

scope can
admin everything, including managing tokens
write every REST edit, including permanent delete from the trash
agent what MCP allows: edits, never a permanent delete, never unprotect
add add items only (browser extension, iPhone Shortcut)
read look only; with folder_ids, only those folders and their subfolders
helper the AI job endpoints only (kist helper on a Mac)

MCP accepts admin, write, agent and read tokens, and each tool checks the scope: a read token can only search, get, view and list.