How do I connect Thumbn to Claude?

Add https://api.thumbn.so/mcp as an MCP server. Claude discovers the authorization server automatically, opens a browser window to sign in to Thumbn, and connects to your own account — you never paste a token. In Claude Code the one-liner is: claude mcp add --transport http thumbn https://api.thumbn.so/mcp

Does it work with Codex, Cursor and other MCP clients?

Yes. The server speaks Streamable HTTP MCP with OAuth 2.1 discovery (RFC 8414 and RFC 9728), which is the standard transport, so any compliant client can connect. Clients that cannot run a browser flow can send a Thumbn API key on the x-api-key header instead.

Can I choose which image model generates the thumbnail?

Yes. Call list_image_models to see what your plan allows, then pass imageModel to create_thumbnail. You can also pick a style preset and which platforms to render for — YouTube at 1280x720, Instagram Reels and TikTok at 1080x1920.

How do I get a Thumbn API key?

Create one in Settings once you are signed in. The key is shown once and stored only as a hash, so copy it when it appears. Send it as x-api-key on any request, or as a bearer token.

Does the API need a subscription?

Yes. Creating thumbnails through the API, the MCP server or the web app all draw on the same plan and the same credit balance — an API key is another way to sign in as yourself, not a separate free tier. Reading your existing projects stays available either way.

What does a thumbnail cost in credits?

Analysing the video costs 2 credits once per job. Each rendered image costs the model's rate — 1 credit for Nano Banana Pro, 2 for GPT Image 2. Instagram Reels and TikTok share one 9:16 render. Call estimate_cost for an exact figure before you spend anything.

API · MCP · agents

The YouTube, TikTok and Instagram Reels thumbnail maker, as an API and an MCP server

Generate thumbnails from your own code, or let Claude, Codex and Cursor make them for you. Same account, same plan, same credits as the web app — and you choose the image model.

Get an API key Connect over MCP

Model Context Protocol

Connect Thumbn to your AI assistant

Thumbn runs a Streamable HTTP MCP server with OAuth 2.1. Point a client at the endpoint and it discovers the authorization server, registers itself and opens a browser to sign you in — there is no token to copy, and the connection is to your own account.

Endpoint

https://api.thumbn.so/mcp

Connect Claude Code

The Claude CLI, in your terminal

Add the server. Nothing to paste — no client id, no token.

claude mcp add --transport http thumbn https://api.thumbn.so/mcp

2
Start the sign-in. Run /mcp inside Claude Code, choose thumbn, then Authenticate. Your browser opens, you sign in to Thumbn, and you approve the connection.
```
/mcp
```
3
Check it worked. Ask Claude to list your image models — it should answer without asking you for a key.
```
claude "using thumbn, what image models can I choose from?"
```

Add -s user to make the server available in every project instead of just the current one. Tokens refresh automatically; revoke with Clear authentication in the same /mcp menu.

Connecting each MCP client to Thumbn

Connect Claude Code

The Claude CLI, in your terminal

Add the server. Nothing to paste — no client id, no token.

claude mcp add --transport http thumbn https://api.thumbn.so/mcp

Start the sign-in. Run /mcp inside Claude Code, choose thumbn, then Authenticate. Your browser opens, you sign in to Thumbn, and you approve the connection.
```
/mcp
```
Check it worked. Ask Claude to list your image models — it should answer without asking you for a key.
```
claude "using thumbn, what image models can I choose from?"
```

Add -s user to make the server available in every project instead of just the current one. Tokens refresh automatically; revoke with Clear authentication in the same /mcp menu.

Connect Claude desktop & web

The Claude app, or claude.ai in a browser

Open Settings → Connectors, and choose Add custom connector.
Paste the Thumbn MCP endpoint as the URL and confirm. Leave every other field empty — there is no client id or secret to provide.
```
https://api.thumbn.so/mcp
```
Sign in and approve. Claude opens Thumbn in a browser tab; approve the connection and you are returned to the app.
Thumbn now appears in the connector list, and its tools are available in any new conversation.

Connect Codex CLI

OpenAI's Codex, in your terminal

Add the server.

codex mcp add thumbn --url https://api.thumbn.so/mcp

Sign in. This opens the same browser flow.
```
codex mcp login thumbn
```
Or, if you prefer editing config directly, add this to ~/.codex/config.toml and then run the login command above. auth = "oauth" is the default and is shown only for clarity.
```
[mcp_servers.thumbn]
url = "https://api.thumbn.so/mcp"
auth = "oauth"
```

Codex prefers the scopes a server advertises. Thumbn advertises openid, profile, email and offline_access — offline_access is what lets your session refresh instead of expiring mid-task.

Connect Codex app

The Codex desktop app

Open Settings → MCP servers, and choose Add server.
Name it thumbn, set the transport to Streamable HTTP, and paste the endpoint as the URL. There is no command to enter — that field is for STDIO servers only.
```
https://api.thumbn.so/mcp
```
Save the server, then choose Restart. The app does not pick up a new server until it restarts.
Sign in. Thumbn will be listed as needing authentication — select Authenticate, and the browser flow opens. Approve the connection and you are returned to the app.
Verify it. Type /mcp in the composer to list connected servers; thumbn should be there with its tools.
```
/mcp
```

The desktop app, the CLI and the IDE extension all share ~/.codex/config.toml, so adding Thumbn in one adds it everywhere. Worth knowing: the desktop app rewrites that file when it starts, so if you keep it in version control, diff it after a desktop session rather than assuming it is untouched.

Connect Cursor

The Cursor editor

Open Cursor Settings → Tools & MCP, and edit mcp.json. Use ~/.cursor/mcp.json for every project, or .cursor/mcp.json for just this one.

Add Thumbn as a remote server. Only the URL is needed.

{
  "mcpServers": {
    "thumbn": {
      "url": "https://api.thumbn.so/mcp"
    }
  }
}

Cursor sees that the server requires authentication and opens the browser flow. Approve, and the tools appear.

Never put an API key in mcp.json if you can avoid it — the file sits in cleartext and gets committed. OAuth avoids the problem entirely, which is why it is the recommended route here.

Connect Any other MCP client

Anything speaking Streamable HTTP

Point the client at the endpoint over Streamable HTTP. Discovery does the rest — an unauthenticated request answers 401 with a WWW-Authenticate header naming the resource metadata, and the client follows it from there.
```
https://api.thumbn.so/mcp
```
Clients that cannot open a browser can authenticate with a Thumbn API key instead, sent on every request.
```
x-api-key: sk_your_key_here
```

Dynamic client registration is supported, so nothing needs pre-registering. Authorization is authorization-code with PKCE (S256); refresh tokens are issued.

Tools

Tool	What it does	Credits
`create_thumbnail`	Watch a YouTube, TikTok or Instagram Reels video and generate thumbnails for it. Returns a job id.	Spends
`get_thumbnail_job`	Check a job's progress and collect the finished images once it completes.	Free
`list_thumbnail_jobs`	List recent projects on the account, newest first.	Free
`list_image_models`	List the image models, style presets and platform sizes available, with the credit cost of each.	Free
`estimate_cost`	Price a run in credits before starting it, so the cost can be confirmed first.	Free
`get_account`	Read the plan, subscription status and remaining credit balance.	Free

REST

Or call the API directly

Create a key in Settings. It authenticates every endpoint the web app uses, as you — so anything you can do in the studio, your code can do too.

1. Start a runPOST /jobs

curl -X POST https://api.thumbn.so/jobs \
  -H "x-api-key: $THUMBN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://www.youtube.com/watch?v=...",
    "platforms": ["youtube", "reels"],
    "imageModel": "nano-banana-pro",
    "variants": 2
  }'

2. Poll until it's doneGET /jobs/{id}

curl https://api.thumbn.so/jobs/$JOB_ID \
  -H "x-api-key: $THUMBN_API_KEY"

# {
#   "job": { "status": "complete", ... },
#   "thumbnails": [
#     { "id": "...", "platform": "youtube", "url": "..." },
#     { "id": "...", "platform": "reels",   "url": "..." }
#   ]
# }

YouTube 1280×720, Reels and TikTok 1080×1920
Choose the image model per request
Six style presets, or your own notes
Reference images for a face, logo or look

Questions

Developer FAQ

How do I connect Thumbn to Claude?: Add https://api.thumbn.so/mcp as an MCP server. Claude discovers the authorization server automatically, opens a browser window to sign in to Thumbn, and connects to your own account — you never paste a token. In Claude Code the one-liner is: claude mcp add --transport http thumbn https://api.thumbn.so/mcp
Does it work with Codex, Cursor and other MCP clients?: Yes. The server speaks Streamable HTTP MCP with OAuth 2.1 discovery (RFC 8414 and RFC 9728), which is the standard transport, so any compliant client can connect. Clients that cannot run a browser flow can send a Thumbn API key on the x-api-key header instead.
Can I choose which image model generates the thumbnail?: Yes. Call list_image_models to see what your plan allows, then pass imageModel to create_thumbnail. You can also pick a style preset and which platforms to render for — YouTube at 1280x720, Instagram Reels and TikTok at 1080x1920.
How do I get a Thumbn API key?: Create one in Settings once you are signed in. The key is shown once and stored only as a hash, so copy it when it appears. Send it as x-api-key on any request, or as a bearer token.
Does the API need a subscription?: Yes. Creating thumbnails through the API, the MCP server or the web app all draw on the same plan and the same credit balance — an API key is another way to sign in as yourself, not a separate free tier. Reading your existing projects stays available either way.
What does a thumbnail cost in credits?: Analysing the video costs 2 credits once per job. Each rendered image costs the model's rate — 1 credit for Nano Banana Pro, 2 for GPT Image 2. Instagram Reels and TikTok share one 9:16 render. Call estimate_cost for an exact figure before you spend anything.

Start with a video link

Every plan includes API and MCP access. Create a key, or connect your assistant, and make your first thumbnail in a minute.

Get an API key