Model Context Protocol
Film references, inside your agent
The FrameThrower MCP server gives any MCP client search access to a cinematography reference library of 5,489 films — indexed frame by frame on lighting, lens character, shot size, colour and mood. Ask for a look in conversation and the agent comes back with real frames, credited to their film, director and cinematographer.
Server URL
https://framethrower.ai/api/mcpOAuth 2.1 · four tools · no rate limits · setup instructions per client →
The four tools
search_frames2 creditsSearch the library by concept, mood, colour, composition or scene, in natural language.
query— string, required · e.g. "neon-lit rainy street at night"limit— number, 1–40, optional · defaults to 12
find_by_craft2 creditsFind frames by specific cinematography attributes. All optional — combine them to narrow.
lens— string, optional · "anamorphic", "spherical", "vintage_soft"shot_size— string, optional · "closeup", "wide", "medium"visual_style— string, optionalsetting— string, optional · "interior" or "exterior"time_of_day— string, optional · "night", "day"director— string, optionalyear_min / year_max— number, optional · year rangelimit— number, 1–40, optional · defaults to 12
find_similar2 creditsPull more frames like one the user already shortlisted. This is the refinement loop.
frameId— string, required · an id from a previous resultlimit— number, 1–40, optional · defaults to 12
get_frame_details2 creditsFull metadata, thumbnail and link for a single frame.
frameId— string, required
How an agent uses it
The server sends usage instructions on connect, so a client does not have to be told how to behave. The shape it asks for is: search, show a small set — about four — with film, director and a link each, then refine on what the user reacts to. Someone saying “more like #2, colder” becomes a find_similar call on that frame, or a find_by_craft with the attributes adjusted.
Every result carries a link back to FrameThrower, because inline image rendering in chat is unreliable and the gallery is where the frames actually look like themselves.
Pricing
$2 of credits free on signup, no card. Each tool call costs 2 credits and $1 = 1,000 credits, so $1 covers 500 calls. Credits never expire and there are no rate limits. Run out and the tool replies with a message saying so, including the balance and where to top up — an agent can read that and tell its user, rather than failing silently.
Also available
A REST API with 11 endpoints and no rate limits (machine-readable spec, docs) and an npm SDK — npm install framethrower-ai. Same account, same credits.
Connect it to your agent
$2 of credits free on signup, no card. Setup takes about a minute.
Sign up for freeCommon questions
- What is the FrameThrower MCP server?
- An MCP (Model Context Protocol) server at https://framethrower.ai/api/mcp that gives an AI agent search access to a cinematography reference library of 5,489 films. Four tools: search_frames, find_by_craft, find_similar and get_frame_details. Connect it in Claude, Cursor or any MCP client and the agent can find real film references mid-conversation.
- How do I connect it?
- Add https://framethrower.ai/api/mcp as a remote MCP server in your client's connector settings. Authentication is OAuth 2.1 — your client opens a FrameThrower sign-in, and after that the agent acts as you, with the same reference access your account has. Cursor supports a one-click install link.
- What does it cost?
- $2 of credits free on signup, no card. Every tool call costs 2 credits, and $1 = 1,000 credits — so $1 covers 500 tool calls. There are no rate limits. When a balance runs out the tool returns a message saying so rather than failing silently.
- Does it return images?
- No image bytes, ever. Tools return metadata, a thumbnail URL and a deep link back to FrameThrower. It is a discovery and reference tool, not an image-delivery pipe — the frames are not ours to license, and rights remain with their owners.
- Is there a REST API too?
- Yes — 11 endpoints with bearer-token auth and no rate limits, plus an npm SDK (npm install framethrower-ai). The machine-readable spec is at framethrower.ai/api/v1 and the docs are at framethrower.ai/developers. Same credits, same account.
More: the stills database · API docs · setup