FrameThrower MCP

Connect an agent

OAuth 2.1 — your client opens a FrameThrower sign-in and there is no key to paste. Free to start, metered against your credit balance.

Introduction

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/mcp

OAuth 2.1 · four tools · no rate limits · setup instructions per client

Connect it

1

Add it as a remote MCP server

In your client's connector settings, add https://framethrower.ai/api/mcp. From the Claude Code CLI that is one command:

claude mcp add --transport http framethrower https://framethrower.ai/api/mcp

2

Sign in

Authentication is OAuth 2.1 — your client opens a FrameThrower sign-in and there is no key to paste. After that the agent acts as you, with the same reference access your account has.

3

Ask for a look

The server sends its own usage instructions on connect, so the client does not have to be told how to behave. Ask for references to a scene and it searches, shows a few, and refines on what you react to.

Clients this is set up and documented for:

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

The MCP server is included in the free plan. A new account gets $2 of credits, no card, and can connect and start calling tools straight away — there is no plan to upgrade to for access. Usage is metered per call, and you buy more credits when you want more calls.

Every tool call 2 credits

search_frames, find_by_craft, find_similar and get_frame_details all cost the same.

$1 1,000 credits

So $1 covers 500 tool calls. Credits never expire.

Top up $20 packs

In Settings → Billing, in whole multiples.

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.

search_frames

TOOL search_frames 2 credits per call

Search the library by concept, mood, colour, composition or scene, in natural language.

query stringrequired

e.g. neon-lit rainy street at night.

limit number

1–40. Defaults to 12.

find_by_craft

TOOL find_by_craft 2 credits per call

Find frames by specific cinematography attributes. All optional — combine them to narrow. At least one is required, or the tool asks for one rather than returning the whole library.

lens string

anamorphic, spherical, vintage_soft

shot_size string

closeup, wide, medium

visual_style string

e.g. noir, naturalistic, stylized

setting string

interior or exterior

time_of_day string

night, day

director string

Full name, e.g. Denis Villeneuve.

year_min / year_max number

Year range.

limit number

1–40. Defaults to 12.

find_similar

TOOL find_similar 2 credits per call

Pull more frames like one the user already shortlisted. This is the refinement loop, and the tool the “more like that one” reply should reach for.

frameId stringrequired

An id from a previous result.

limit number

1–40. Defaults to 12.

get_frame_details

TOOL get_frame_details 2 credits per call

Full metadata, thumbnail, depth map and link for a single frame.

frameId stringrequired

An id from a previous result.

What comes back

Every tool returns frames as text an agent can quote: the film with its year, director and cinematographer, the craft attributes behind the shot, a thumbnail URL, the full-resolution image URL, and a link to the frame on FrameThrower. Plus a link to the same search as a gallery, for when the reader wants to keep going by hand.

Each frame also carries a depth map — greyscale, the same dimensions as the frame, precomputed for all 410,000 of them. An agent building a shot can hand that straight to a depth ControlNet to keep a reference's composition and camera geometry while changing everything else. It costs no extra credits and needs no extra call; the line is simply there in the result.

No image bytes, ever. This is a discovery and reference tool, not an image-delivery pipe — the frames are not ours to license, and rights remain with their owners. See the Intended Use Policy.

REST API too

The MCP server is four tools over the same library a REST API of eleven endpoints reaches — and the REST side has the three the tools do not: image search, colour search and the film catalogue. Same account, same credits.

npm install framethrower-ai

Common 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?

It is included in the free plan — there is no tier to upgrade to for access. A new account gets $2 of credits, no card. Every tool call costs 2 credits and $1 = 1,000 credits, so $1 covers 500 tool calls, and you buy more credits per use when you want more calls. Credits never expire and 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: setup per client · API docs · the stills database