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.

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.

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.

API reference contents

FrameThrower MCP server

Film references inside your agent. Four tools over OAuth 2.1, across a cinematography library of 5,489 films.

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.

Connect an agent Setup steps

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

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

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.

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:

Claude

Claude Code and the desktop app — connector settings or one CLI command

Cursor

One-click install link

ChatGPT

Add as a remote MCP connector

Any MCP client

OpenClaw, Hermes, or anything that speaks streamable HTTP

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 call2 credits

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

$11,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

TOOLsearch_frames2 credits per call

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

querystringrequired

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

limitnumber

1–40. Defaults to 12.

find_by_craft

TOOLfind_by_craft2 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.

lensstring

anamorphic, spherical, vintage_soft

shot_sizestring

closeup, wide, medium

visual_stylestring

e.g. noir, naturalistic, stylized

settingstring

interior or exterior

time_of_daystring

night, day

directorstring

Full name, e.g. Denis Villeneuve.

year_min / year_maxnumber

Year range.

limitnumber

1–40. Defaults to 12.

find_similar

TOOLfind_similar2 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.

frameIdstringrequired

An id from a previous result.

limitnumber

1–40. Defaults to 12.

get_frame_details

TOOLget_frame_details2 credits per call

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

frameIdstringrequired

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.

API reference

Eleven endpoints, one bearer token, no rate limits

OpenAPI spec

Machine-readable, for agents that consume schemas

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