Technical update
Inside Holo Folder’s MCP server: your collection, in your AI assistant
Compatible AI assistants get the same 70 tools as our REST API, built from the same definitions as the app. Here is why we keep them in step, and what you can do with them, from a screenshot to a filled binder page.
MCP, the Model Context Protocol, is how an AI assistant such as Claude, ChatGPT, Cursor or Codex uses tools in another product. Holo Folder has had an MCP server since early November, and it now has 70 tools covering card search, binders, owned cards, want lists, prices, sharing, partners, show purchases and Activity history.
This post explains how the server is built, why we keep it level with the app, and five things worth trying once you are connected.
Why the MCP server has to keep up with the app
Most integrations are built once and then drift. The app gains a feature, the API does not, and the assistant you connected last month can describe your binders but cannot move a page. For an assistant, a missing tool is worse than a missing button. It will try to reach the same result another way, usually with several small edits that the app would have made as one careful change.
So we treat the MCP server as part of the product rather than a side project. Three rules keep it that way.
One definition for every surface
Each operation is written down once: its name, its inputs, the permissions it needs and a description of what it does. That one definition becomes the REST endpoint, the MCP tool, the OpenAPI document and the page in our API reference. There is no second list of tools to forget about. If move_binder_page exists in the REST API, your assistant has it too, with the same name and the same inputs.
The same code as the app
Tools do not call a separate API version of a feature. They run the same server operations the app uses, with the same checks. Partner access, revision checks and Activity history behave the same whether a change comes from your phone, from a script or from Claude.
Features ship with their tools
Every feature we release ships with its API, its MCP tool and its documentation in the same change. When page suggestions arrived in the app, suggest_cards arrived for your assistant. When layout editing arrived, so did set_binder_layout and move_binder_page. A feature is not finished until it is available here as well.
A few things stay in the app on purpose:
Stays in the app | Why |
|---|---|
Camera, scanning and on-device text reading | It runs on your phone. The picture matcher behind it is available as |
Billing, account deletion and API key management | These need you, signed in on the website. |
Offline storage and the edit queue | They live on your device. |
Every example in the docs works in your assistant
Because each tool and its endpoint come from the same definition, every example in the developer docs is also an MCP example. The JSON in a guide is the tool’s input, and the response it shows is the tool’s structured output.
Docs guide | MCP tool |
|---|---|
Identify a card from a photo |
|
Change a binder’s grid with a dry run |
|
Move a whole page |
|
Fill, move and clear pockets |
|
Similar cards and page suggestions |
|
Check an asking price |
|
Collection history and Undo |
|
Tools also tell your assistant how careful to be. Each one is marked as read-only or not, and writes that replace or remove things are marked as destructive, so clients that ask before risky actions know when to ask. Errors come back with the same codes as the REST API, such as 409 when something changed since your assistant last looked.
Five things to try
1. From a screenshot to a binder
Screenshot a set list, a friend’s trade list or the cards you picked up today, drop it into the chat and ask your assistant to add them. It reads the names and collector numbers from the image, finds each exact printing with list_cards, shows you what it found, and only then places the cards with execute_inventory_commands. Anything it cannot match is left for you to choose.
“Here is a screenshot of the cards I bought today. Find each exact printing and show me the list. Once I say yes, add them to the empty pockets at the end of my Kanto binder.”
Working from photos of the cards themselves? A coding agent that can read image files, such as Claude Code or Codex, can send each photo to identify_card. It is the same picture matcher as the in-app scanner. It returns likely cards with a confidence label and only confirms one when the collector number you read agrees. Each connection can identify 20 photos a minute.
2. Rearrange a binder without touching a sleeve
Ask for a new grid and your assistant runs set_binder_layout as a dry run first, so you see which cards change page or position before anything moves. Applying it is one change in Activity, and you can undo it from the app. To swap two pages, move_binder_page moves a whole page in one step.
“Switch my Base Set binder to 3×4 pages. Tell me which cards move before you change anything.”
3. Check a deal at a show
Give your assistant the asking price and the card. check_deal compares it with the saved market evidence for that exact printing and finish, using the same rules as the deal checker in Show mode. If we do not have good evidence, it says so rather than guessing.
“Someone is asking £45 for a near-mint Umbreon VMAX 215/203. Is that a fair price?”
4. Plan the next page
suggest_cards looks at the cards already on a binder page and suggests others that would fit, by picture first and then by shared Pokémon, illustrator, type or set. Pair it with your want list and saved prices to plan what to buy next.
“Look at page 3 of my Eeveelutions binder and suggest five cards that would fit, cheapest first. Don’t add anything yet.”
5. See what changed, and put it back
Every collection change lands in Activity, whether it was made in the app, by a partner or by an assistant. Your assistant can read it with list_collection_audit and preview an undo before applying it. Certificates, labels and other private details never leave the server.
“What changed in my collection yesterday? If anything was removed from my Gold Star binder, show me how to undo it.”
You stay in control
You sign in with your Holo Folder account. There is no API key to paste and no local server to run.
The consent screen shows which client is asking and what it wants to access. Start with read access. Writes, sharing and partner changes need your explicit approval.
Collection changes made by an assistant are recorded in Activity and can be undone like any other edit.
You can revoke a connection at any time in Settings → Account → Developer access.
Missing prices stay missing. Tools return the evidence we hold and how confident it is, never an invented number.
Get connected
Developer access needs a current Premium subscription or lifetime licence. Signup trials do not include it, and partners follow the collection owner’s access.
Add this server in your client and choose OAuth when asked: https://app.holofolder.com/app/mcp
The developer docs have setup guides for Claude, ChatGPT, Cursor and Codex. If your agent runs on another machine or over SSH, the consent screen can hand the sign-in back to it.
Open your collection