# Thumbn for developers and AI agents

Make YouTube, TikTok and Instagram Reels thumbnails from your own code, or connect Thumbn to Claude, Codex and Cursor over MCP with OAuth. REST API, API keys, and six tools including your choice of image model.

## MCP server

Endpoint: `https://api.thumbn.so/mcp` (Streamable HTTP)

Authorization is OAuth 2.1 against Thumbn's own authorization server, discoverable at
`https://api.thumbn.so/.well-known/oauth-authorization-server` and
`https://api.thumbn.so/.well-known/oauth-protected-resource`. Dynamic client registration is
supported, so a client can connect without pre-registration.

### Connecting each client

**Claude Code** — The Claude CLI, in your terminal

1. 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._

**Claude desktop & web** — The Claude app, or claude.ai in a browser

1. Open Settings → Connectors, and choose Add custom connector.
2. 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
   ```
3. Sign in and approve. Claude opens Thumbn in a browser tab; approve the connection and you are returned to the app.
4. Thumbn now appears in the connector list, and its tools are available in any new conversation.

**Codex CLI** — OpenAI's Codex, in your terminal

1. Add the server.

   ```
   codex mcp add thumbn --url https://api.thumbn.so/mcp
   ```
2. Sign in. This opens the same browser flow.

   ```
   codex mcp login thumbn
   ```
3. 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._

**Codex app** — The Codex desktop app

1. Open Settings → MCP servers, and choose Add server.
2. 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
   ```
3. Save the server, then choose Restart. The app does not pick up a new server until it restarts.
4. 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.
5. 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._

**Cursor** — The Cursor editor

1. Open Cursor Settings → Tools & MCP, and edit mcp.json. Use ~/.cursor/mcp.json for every project, or .cursor/mcp.json for just this one.
2. Add Thumbn as a remote server. Only the URL is needed.

   ```
   {
     "mcpServers": {
       "thumbn": {
         "url": "https://api.thumbn.so/mcp"
       }
     }
   }
   ```
3. 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._

**Any other MCP client** — Anything speaking Streamable HTTP

1. 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
   ```
2. 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

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

## REST API

Authenticate with a Thumbn API key on `x-api-key` (create one in Settings). The same key
works on every endpoint the web app uses, as the same user, on the same plan.

```bash
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
  }'
```

Poll `GET https://api.thumbn.so/jobs/{id}` until `status` is `complete`, then read the
`thumbnails` array.

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

---

Thumbn — AI thumbnail generator for YouTube, TikTok and Reels. https://thumbn.so