# Thumbn MCP Server

The Thumbn MCP server lets an AI assistant make thumbnails for you. Its endpoint is `https://api.thumbn.so/mcp` (Streamable HTTP). The assistant signs in to your Thumbn account with OAuth 2.1, so you never paste a token, and it uses your plan and credits.

## Endpoint and sign-in

- Endpoint: `https://api.thumbn.so/mcp`
- Transport: Streamable HTTP
- Authorization: OAuth 2.1 with dynamic client registration. Metadata at `https://api.thumbn.so/.well-known/oauth-authorization-server` and `https://api.thumbn.so/.well-known/oauth-protected-resource`.
- Without a browser: send a Thumbn API key on the `x-api-key` header.
- Server card: https://thumbn.so/.well-known/mcp/server-card.json

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

Runs are asynchronous. Call `create_thumbnail`, then poll `get_thumbnail_job` until its status is `complete`.

## Connect a 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?"
   ```

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

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

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

## Related

- [REST API documentation](https://thumbn.so/developers.md)
- [OpenAPI specification](https://thumbn.so/openapi.json)
- [Authentication](https://thumbn.so/auth.md)
