Connect The Movie Database (TMDB) to ChatGPT: Sync Lists & Ratings

If you need to connect The Movie Database (TMDB) to ChatGPT to automate media research, synchronize watchlists, manage user ratings, or curate content for a streaming platform, you need a Model Context Protocol (MCP) server. This infrastructure layer acts as the real-time translator between the Large Language Model's function calls and TMDB's REST APIs. If your team uses Claude instead, check out our guide on connecting The Movie Database (TMDB) to Claude, or read our higher-level architectural overview on connecting The Movie Database (TMDB) to AI Agents.

Giving an AI agent read and write access to TMDB is an engineering challenge. The platform's API is deeply interconnected, requires distinct authentication models depending on the operation, and enforces aggressive rate limits. You can either build, host, and maintain a custom MCP server yourself, or you can use a managed platform like Truto to dynamically generate a secure, authenticated MCP server URL.

This guide breaks down exactly how to use Truto to generate an MCP server for TMDB, connect it natively to ChatGPT, and execute complex workflows using natural language.

The Engineering Reality of the TMDB API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against a specific vendor's API is painful. You own the entire API lifecycle.

If you decide to build a custom MCP server for TMDB, here are the specific integration challenges that break standard CRUD assumptions:

Authentication Fragmentation TMDB utilizes a fragmented authentication model. Some endpoints require a simple API Key. Others require a v3 Session ID (generated via a complex multi-step request token flow), while newer endpoints utilize a v4 Bearer Token. Guest sessions are treated entirely differently from user sessions. If you build a custom MCP server, you must dynamically map the correct authentication context to every single LLM tool call based on the endpoint being accessed.

The Image Pathing Problem Unlike most modern REST APIs that return fully qualified URLs for media assets, TMDB returns relative file paths for images (e.g., /kqjL17yufvn9OVLyXYpvtyrFfak.jpg). To construct a valid URL, your server must periodically query the /configuration endpoint to retrieve the secure_base_url and available image sizes, then append the file path. If you pass raw relative paths to ChatGPT, the model will hallucinate base URLs, resulting in broken image links in the chat UI.

Handling Rate Limits and 429 Errors TMDB enforces strict rate limiting rules based on IP and account. When building your integration layer, note that Truto does not absorb, retry, or apply backoff to upstream rate limit errors. When TMDB returns an HTTP 429 Too Many Requests response, Truto passes that error directly to the caller. However, Truto normalizes TMDB's proprietary rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset).

This means the caller (your orchestration layer or ChatGPT itself) is responsible for executing the exponential backoff. Your MCP integration must explicitly instruct the LLM to inspect these headers and pause execution if a 429 is encountered, rather than hallucinating a successful tool execution.

Pagination and Cursor Handling When an LLM requests a list of "Popular Movies," TMDB returns a paginated response. LLMs cannot magically infer how to fetch the next page. You must explicitly inject instructions into the tool's JSON Schema telling the LLM exactly how to handle the page or next_cursor parameter, returning the value unmodified in subsequent calls.

Creating the TMDB MCP Server

Instead of writing and maintaining a custom JSON-RPC router and reverse-engineering TMDB's schemas, you can use Truto to generate a managed MCP server.

Truto derives MCP tools dynamically from the TMDB integration's resource definitions. A tool only appears in the MCP server if it has corresponding documentation records defining the query schema, body schema, and descriptions. This acts as a quality gate ensuring the LLM understands exactly how to format its requests.

You can spin up this server using either the Truto UI or the REST API.

Option 1: Via the Truto UI

If you prefer a visual interface, you can generate the server directly from the dashboard.

1. Log into Truto and navigate to your Integrated Accounts.
2. Select your connected The Movie Database (TMDB) instance.
3. Click on the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration. You can filter the server to only allow read methods, or restrict it to specific tags like movies or tv_shows.
6. Click Generate and copy the resulting https://api.truto.one/mcp/... URL.

This single URL contains a cryptographically hashed token that securely identifies your TMDB account, the specific tool filters, and the expiration policy.

Option 2: Via the Truto API

For platform engineers building multi-tenant AI products, you need to generate these servers programmatically.

Make an authenticated POST request to the /integrated-account/:id/mcp endpoint. You can enforce granular constraints - for example, generating a temporary, read-only server dedicated strictly to TV show operations.

// POST /integrated-account/:id/mcp
{
  "name": "TMDB Editorial AI Server",
  "config": {
    "methods": ["read"],            // Restrict to GET/LIST operations only
    "tags": ["tv_shows", "movies"]  // Only expose tools related to these domains
  },
  "expires_at": "2026-12-31T23:59:59Z"
}

Truto validates that the TMDB integration has tools available, generates a secure token, stores it in distributed KV storage, and returns a ready-to-use URL:

{
  "id": "mcp_abc123",
  "name": "TMDB Editorial AI Server",
  "config": { "methods": ["read"], "tags": ["tv_shows", "movies"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to ChatGPT

Once you have your Truto MCP URL, connecting it to your AI client takes seconds. We will cover both the standard ChatGPT UI approach and the developer-centric Server-Sent Events (SSE) configuration file approach.

Method A: Via the ChatGPT UI

OpenAI natively supports custom MCP connectors in its advanced settings.

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Toggle Developer mode to the ON position (MCP support is currently behind this flag for Pro, Plus, Enterprise, and Edu accounts).
3. Under the MCP servers / Custom connectors section, click Add new server.
4. Enter a human-readable name (e.g., "TMDB Content Manager").
5. Paste the Truto MCP URL into the Server URL field.
6. Click Save.

ChatGPT will immediately ping the server, complete the JSON-RPC handshake, and populate its context window with the available TMDB tools.

Method B: Via Manual Config File (SSE Transport)

If you are running an AI agent orchestration framework locally (like Claude Desktop, Cursor, or a LangChain agent), you configure the MCP server using a JSON configuration file. Truto's managed MCP servers use Server-Sent Events (SSE) for transport, so you utilize the official @modelcontextprotocol/server-sse package.

Create or update your MCP configuration file (e.g., mcp-config.json):

{
  "mcpServers": {
    "tmdb-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

Restart your client, and the agent will instantly discover the TMDB API surface.

Core TMDB Tools for AI Agents

Truto automatically generates descriptive, snake_case tool names from TMDB's resource endpoints.

Here are the hero tools your AI agent will rely on to manage movies, TV shows, and user data. Note: Only a subset of tools is shown below. For the complete TMDB integration schema and full tool inventory, visit the TMDB integration page.

Search Multiple Media Types

Tool: list_all_the_movie_database_tmdb_search_multis

This is the most critical tool for conversational search. It allows the LLM to search TMDB for movies, TV shows, and people in a single request. The response fields vary depending on the media_type of the returned objects.

"Search TMDB for 'The Last of Us' and tell me if it returns a TV show or a video game adaptation."

Get Detailed Movie Information

Tool: get_single_the_movie_database_tmdb_3_movie_by_id

Fetches the top-level details of a movie by its TMDB ID. It returns granular data including runtime, budget, revenue, genres, and the overall vote average.

"Fetch the full details for the movie with ID 157336. What was its production budget compared to its total revenue?"

Discover Movies via Filters

Tool: list_all_the_movie_database_tmdb_discover_movies

A powerful querying tool that allows the LLM to filter movies using over 30 parameters, including release date, vote average, original language, and specific genre IDs.

"Find me the top-rated science fiction movies released between 2015 and 2020 that have a minimum of 5,000 votes."

Fetch Account States for a Movie

Tool: list_all_the_movie_database_tmdb_account_states

Before an AI agent attempts to rate a movie or add it to a watchlist, it should check the current state. This tool returns the active user's rating, watchlist status, and favorite status for a specific movie ID.

"Check if I have already added 'Dune: Part Two' (ID: 693134) to my watchlist or marked it as a favorite."

Add a Rating to a Movie

Tool: create_a_the_movie_database_tmdb_rating

Allows the LLM to submit a rating (from 0.5 to 10.0) for a movie, saving it directly to the authenticated user's rated list.

"Rate the movie 'Oppenheimer' an 8.5 out of 10 on my TMDB account."

Manage the Account Watchlist

Tool: create_a_the_movie_database_tmdb_watchlist

Adds or removes a movie or TV show from the user's watchlist. The LLM must pass the account_id and a JSON body specifying the media_type, media_id, and watchlist boolean flag.

"Add the TV series 'Severance' (ID: 95396) to my TMDB watchlist."

For the complete list of available operations - including endpoints for TV seasons, episodes, cast credits, and image galleries - check out the TMDB integration page.

Workflows in Action

When you expose these proxy APIs to ChatGPT via MCP, the model stops acting as a static search engine and becomes an autonomous media assistant. Here are two real-world workflows demonstrating how the LLM chains tools together.

Workflow 1: The Automated Content Curator

Persona: A film enthusiast organizing their upcoming weekend viewing schedule.

User Prompt: "Find Denis Villeneuve's highest rated science fiction movie. Check if it's already on my watchlist. If it isn't, add it. Then tell me the runtime."

sequenceDiagram
    participant User
    participant ChatGPT
    participant MCP as Truto MCP Server
    participant TMDB as TMDB API
    
    User->>ChatGPT: "Find Villeneuve's top sci-fi..."
    ChatGPT->>MCP: Call list_all_the_movie_database_tmdb_discover_movies<br>{"with_people": "137427", "with_genres": "878", "sort_by": "vote_average.desc"}
    MCP->>TMDB: GET /3/discover/movie
    TMDB-->>MCP: Movie Array (Top result: Dune: Part Two, ID: 693134)
    MCP-->>ChatGPT: Result data
    
    ChatGPT->>MCP: Call list_all_the_movie_database_tmdb_account_states<br>{"movie_id": 693134}
    MCP->>TMDB: GET /3/movie/693134/account_states
    TMDB-->>MCP: {"watchlist": false}
    MCP-->>ChatGPT: Account state data
    
    ChatGPT->>MCP: Call create_a_the_movie_database_tmdb_watchlist<br>{"account_id": "1234", "RAW_BODY": {"media_type": "movie", "media_id": 693134, "watchlist": true}}
    MCP->>TMDB: POST /3/account/1234/watchlist
    TMDB-->>MCP: Success
    MCP-->>ChatGPT: Confirmation
    
    ChatGPT->>MCP: Call get_single_the_movie_database_tmdb_3_movie_by_id<br>{"id": 693134}
    MCP->>TMDB: GET /3/movie/693134
    TMDB-->>MCP: {"runtime": 166}
    MCP-->>ChatGPT: Movie details
    ChatGPT-->>User: "I found Dune: Part Two. It wasn't on your watchlist, so I added it. The runtime is 166 minutes."

What happens: ChatGPT first queries the discovery tool using the director's person ID and the sci-fi genre ID. It isolates the top result (Dune: Part Two), checks the account states to verify if it is already watchlisted, executes the POST request to update the watchlist, and finally fetches the specific movie details to report the runtime back to the user.

Workflow 2: TV Show Deep-Dive & Rating

Persona: An entertainment blogger conducting research for a review article.

User Prompt: "Search for the TV show 'Shōgun'. Give me a summary of the show, tell me how many episodes it has, and rate the show a 9.0 on my account."

sequenceDiagram
    participant User
    participant ChatGPT
    participant MCP as Truto MCP Server
    participant TMDB as TMDB API
    
    User->>ChatGPT: "Search for Shōgun..."
    ChatGPT->>MCP: Call list_all_the_movie_database_tmdb_search_tvs<br>{"query": "Shōgun"}
    MCP->>TMDB: GET /3/search/tv?query=Shōgun
    TMDB-->>MCP: TV Result (ID: 126308)
    MCP-->>ChatGPT: TV overview
    
    ChatGPT->>MCP: Call get_single_the_movie_database_tmdb_3_tv_by_id<br>{"id": 126308}
    MCP->>TMDB: GET /3/tv/126308
    TMDB-->>MCP: {"number_of_episodes": 10, "overview": "..."}
    MCP-->>ChatGPT: Detailed TV metadata
    
    ChatGPT->>MCP: Call the_movie_database_tmdb_tvs_add_rating<br>{"series_id": 126308, "RAW_BODY": {"value": 9.0}}
    MCP->>TMDB: POST /3/tv/126308/rating
    TMDB-->>MCP: Success
    MCP-->>ChatGPT: Confirmation
    ChatGPT-->>User: "Shōgun is a 10-episode historical drama... I have rated it 9.0 for you."

What happens: The model uses the search tool to find the correct TMDB series ID. It takes that ID and fetches the full show metadata to extract the episode count and summary. It then formats a POST request body with the numerical value to submit the rating to the user's account.

Security and Access Control

Giving an LLM unconstrained access to a third-party account is risky. If an AI hallucinates a command, it could accidentally clear a custom list or delete user ratings. Truto's MCP servers provide strict access controls at the infrastructure level:

• Method Filtering: When you create the server, you can restrict config.methods to ["read"]. This drops all create, update, and delete tools from the LLM's context window entirely. The AI physically cannot mutate data.
• Tag Filtering: You can use config.tags to limit the server's scope. If you only want the AI to interact with movies and never touch tv_shows or people, you can enforce that at the server level.
• Extra Authentication (require_api_token_auth): By default, possessing the MCP URL grants access to the tools. For enterprise environments, you can toggle require_api_token_auth: true. This forces the client to also pass a valid Truto API token in the headers, adding a robust secondary authentication layer.
• Auto-Expiring Servers: If you are provisioning an AI agent for a temporary contractor or a short-lived automated workflow, use the expires_at property. The system schedules a cleanup alarm that automatically purges the server from the database and KV storage when time is up.

Moving Past Manual Integration Boilerplate

Connecting The Movie Database to ChatGPT shouldn't require your engineering team to spend weeks wrangling authentication tokens, formatting image URLs, and writing custom JSON-RPC routers. By utilizing a managed MCP infrastructure, you treat APIs as declarative data sets rather than codebases.

Truto handles the underlying schema generation, token storage, and protocol routing, allowing you to focus purely on prompt engineering and workflow orchestration. The AI gets accurate schemas, and your application gets real-time, authenticated access to one of the world's largest media databases.