Manage your personal movie watchlist, get AI-powered recommendations, and interact with beautiful widgets directly in ChatGPT. Movie data powered by . Features multi-provider LLM support and PostgreSQL for data persistence.
An OpenAI App demo built with the OpenAI Apps SDK, that's ready to deploy on Render.
Note: Only the get_recommendations tool requires an LLM API key. All other features work with just the TMDB API key.
Widgets
Interactive UI components rendered in ChatGPT:
Movie Poster - Full details view with cast, backdrop, and quick actions (add to watchlist, mark watched)
Movie List - Sortable grid for search results and watchlists with inline actions
Preferences - Visual editor for favorite genres, actors, directors (helps AI recommendations)
Multi-provider AI
Recommendations support OpenAI (GPT-5), Anthropic (Claude Sonnet 4.5), or Gemini (2.5 Flash). Auto-detects based on available API key.
Performance & Caching
Built-in Valkey caching for optimal performance:
TMDB API calls - Person searches (7 days) and movie details (30 days)
User preferences - Cached for 5 minutes with automatic invalidation on updates
Result: Sub-millisecond response times for cached data vs. 200-300ms API calls
Valkey is automatically provisioned on Render thanks to our blueprint setup. No additional configuration needed.
Getting started
Quick start: Deploy to Render
This app is designed to be deployed to Render with zero configuration. The included render.yaml blueprint automatically provisions everything you need.
Prerequisites
Get your API keys ready (you'll add them during deployment):
Connect your GitHub account and select your forked repository
Render will detect the render.yaml file automatically
3. Add your API keys as environment variables
When prompted, add these secret environment variables:
Variable
Required?
Description
TMDB_API_KEY
✅ Required
Your TMDB API key (for all movie data)
OPENAI_API_KEY
🤖 Optional*
OpenAI API key (GPT-5 for recommendations)
ANTHROPIC_API_KEY
🤖 Optional*
Anthropic API key (Claude Sonnet 4.5 for recommendations)
GEMINI_API_KEY
🤖 Optional*
Google Gemini API key (2.5 Flash for recommendations)
ADMIN_API_KEY
✨ Recommended
Your personal MCP access key (auto-generated if not set)
ADMIN_EMAIL
Optional
Admin user email (defaults to admin@localhost)
*At least one LLM API key is required if you want to use the get_recommendations tool. All other features (search, watchlist, preferences, etc.) work without any LLM.
Free tier note: The provided Render blueprint is preconfigured so every service runs on free plans (the managed Postgres instance is free for the first 30 days). Free services spin down when idle, so the first request after a long pause may be slow or occasionally time out. Once instance is active, everything behaves normally. If you want production-like responsiveness, bump the services to Starter or Standard plans.
Click Apply and Render will:
✅ Provision a PostgreSQL database
✅ Provision a Valkey cache (for performance)
✅ Deploy the backend Node.js service
✅ Deploy the frontend widget static site
✅ Run database migrations automatically
✅ Link everything together
✅ Assign HTTPS domains
That's it! In ~5 minutes your app will be live at:
Copy the OpenAI App MCP URL, you'll need it at Step 3 below
Step 2: Enable developer mode (first time only)
Open ChatGPT and go to Settings (gear icon in bottom left)
Navigate to Apps and connectors
Scroll down and click Advanced settings
Enable Developer mode
Step 3: Create your OpenAI app
Go back to Apps and connectors
Click Create (or New connector)
Fill in the connector details:
Name: Movie Context Provider (or any name you prefer)
Description (optional): Brief description of what it does
MCP Server URL: Paste the OpenAI App MCP URL value you copied from the server logs at step 1. It should look something likehttps://your-app-name.onrender.com/mcp/messages?api_key=your_API_key_here
Authentication: select No Auth
Check "I trust this application" (required for custom connectors)
Click Create
ChatGPT will test the connection and add the MCP server.
Step 4: Enable the app in a chat
Important: The app won't work until you enable it in a ChatGPT conversation.
AI recommendations support three providers (priority: OpenAI → Anthropic → Gemini):
Provider
Model
Notes
OpenAI
GPT-5
Latest reasoning model
Anthropic
Claude Sonnet 4.5
Best speed/intelligence balance
Gemini
Gemini 2.5 Flash
Best price/performance, free tier
Set any one API key to enable the get_recommendations tool. Models are fixed and auto-detected based on available keys.
Authentication & user management
Demo Authentication Note
This project uses simple API key authentication as a shortcut for demo purposes. Each API key serves as both authentication and user identification, making it easy to support multiple users without complex OAuth flows.
For production apps, consider implementing OAuth 2.0, which provides:
Secure user consent flows
Token expiration and refresh
Revocable access without password changes
Industry-standard security practices
The API key approach here is intentionally simplified to focus on showing MCP and OpenAI app SDK concepts rather than authentication best practices.
Automatic admin user setup
Good news! If you set ADMIN_API_KEY during deployment, an admin user is automatically created during database migration. You can immediately connect using your admin key:
# Your ADMIN_API_KEY works as both:
# 1. Protection for /admin endpoints
# 2. Your personal MCP API key
# Connect immediately after deployment
https://movie-mcp-server.onrender.com/mcp/messages?api_key=YOUR_ADMIN_API_KEY
Creating additional users
Use the admin endpoint to create users for others:
User: Search for sci-fi movies from 2010
→ Displays movie list widget with Inception, Tron Legacy, etc.
User: Tell me about Inception
→ Displays movie poster widget with full details
User: Add it to my watchlist
→ Confirms added, updates widget state
User: Mark Inception as watched, 5 stars
→ Saves rating, removes from watchlist
User: Show my watchlist
→ Displays watchlist in list widget (sortable, filterable)
User: Recommend me some movies for a cozy evening
→ AI analyzes your taste, displays personalized recommendations
Advanced queries
"Find highly-rated Christopher Nolan movies"
"Show me popular action movies from the 90s"
"Give me Tom Hanks movies I haven't watched"
"Recommend thought-provoking sci-fi like Arrival"
"What's in my watchlist?"
"Show my highest-rated movies"
Local development (optional)
Want to develop or test locally before deploying? Here's how:
Prerequisites
Node.js 20+
PostgreSQL 15+ (local instance or Docker)
Your API keys from above
Setup steps
1. Clone your forked repository
git clone https://github.com/YOUR_USERNAME/movie-context-provider
cd movie-context-provider
2. Install dependencies
# Backend
cd backend
npm install
# Frontend
cd ../frontend
npm install
3. Configure environment
cd backend
cp env.example .env
Edit .env with your local database and API keys:
# Local database
DATABASE_URL=postgresql://user:password@localhost:5432/movies_db
# API Keys (same as Render)
TMDB_API_KEY=your_tmdb_api_key
OPENAI_API_KEY=your_openai_api_key
# Local URLs
MOVIE_POSTER_WIDGET_URL=http://localhost:5173
PORT=3000
NODE_ENV=development
4. Set up database
cd backend
npm run migrate
Creates tables and a demo user: [email protected] / API key: demo_api_key_change_in_production
5. Run development servers
# Terminal 1 - Backend (with hot reload)
cd backend
npm run dev
# Terminal 2 - Frontend widgets (with hot reload)
cd frontend
npm run dev
npm run dev # Hot reload (tsx watch)
npm run build # Compile TypeScript
npm start # Run compiled code
npm run migrate # Run database migration
npm run type-check # TypeScript check
Frontend:
npm run dev # Dev server with hot reload
npm run build # Build both widgets
npm run build:poster # Build poster widget only
npm run build:list # Build list widget only
echo $MOVIE_POSTER_WIDGET_URL
# Should be: https://your-frontend.onrender.com
Database connection issues
# Test connection
psql $DATABASE_URL
# Render requires SSL:
DATABASE_URL=postgresql://user:pass@host:5432/db?sslmode=require
LLM provider issues
Check which provider is being used:
# Backend logs will show:
🤖 Using OPENAI for recommendations
Verify API key is set:
echo $OPENAI_API_KEY
# Should output your key
Gotchas & known issues
1. The 424 Error: structuredContent Must Be Objects
Problem: Intermittent 424 Failed Dependency errors in ChatGPT when calling tools like set_preference and add_to_watchlist.
What We Learned:
This was one of our toughest debugging challenges. Here's what made it tricky:
The error appeared inconsistently across different tools, making it seem like unrelated issues
Backend logs showed success - our server returned 200 OK with valid JSON
No client-side error details - ChatGPT UI displayed "Tool failed with status 424" without specifics
The bug was subtle - responses looked correct and followed MCP protocol structure
After careful debugging and comparing working vs. failing tool responses, we discovered the root cause:
The Solution:
The OpenAI Apps SDK expects toolOutput to be an object (hinted by the TypeScript type ToolOutput extends UnknownObject). Primitive values are rejected:
Compare working tool responses with failing ones byte-by-byte
Check if any structuredContent returns primitives (boolean, string, number)
Always wrap simple values in objects: { success: true } not true
Use TypeScript for better type hints (though runtime validation would still help)
For OpenAI SDK Team: Adding runtime validation with descriptive errors (e.g., "structuredContent must be an object, received: boolean") would significantly improve the developer experience and reduce debugging time for this common mistake.
Key Takeaway: When your tool response includes structuredContent, it must be an object (not a primitive like true, "success", or 42). If you don't need to pass structured data to a widget, you can omit structuredContent entirely and just use content.
2. Widget Data Passing Issues
Problem: Initially struggled with passing movie data from backend to widgets.
Evolution:
First attempt: Used _meta to hide data from model → Data didn't reach widget
Second attempt: Used widgetDescription in _meta → Model still showed duplicate content
Final solution: Put data in structuredContent and keep content concise
Lesson:structuredContent is the reliable way to pass data to widgets. Keep content brief (summary for the model), and widgets read from toolOutput.structuredContent.
3. ChatGPT Shows Text Content Below Widgets
What happens: Even when your tool returns a widget, ChatGPT often displays additional plain text content below it, duplicating information already shown in the widget.
Why this happens: This appears to be intentional behavior by OpenAI. The model uses the content field from your tool response to generate a textual summary, which it displays alongside the widget.
Not configurable from code: There's no metadata flag or option to disable this text output from the backend.
Workaround: You can instruct ChatGPT at the conversation level:
"For this movie app, please show only the widget without additional text explanations when displaying movie details or lists."
This user-level prompt can guide ChatGPT to be less verbose, though the behavior may still vary depending on the conversation context.
4. Widget Build Size Considerations
Each widget is ~260 KB because:
Fully self-contained (includes React, all dependencies)
No code splitting (required for widget independence)
Bundles its own copy of shared utilities
This is intentional - OpenAI Apps SDK requires self-contained widget bundles. The tradeoff is larger file sizes for simpler deployment and reliability.
Next steps & ideas
Feature Extensions
TV Shows Support
Add similar tools for TV series using TMDB's TV endpoints
Track episodes watched, season progress
Recommendations for "if you liked X, watch Y"
Analytics & Insights
"Your most-watched genres this year"
"Average rating by director"
"Movies watched over time" graphs
Genre preference trends
🎬 Streaming Integration
Show which services have each movie (JustWatch API)
Filter searches by "available on Netflix"
Track which services you subscribe to
Technical Improvements
Authentication: OAuth 2.0, JWT tokens with refresh
Testing: Unit tests for tools, integration tests, E2E for MCP
This project uses the Streamable HTTP transport, which is the recommended modern approach for MCP servers (as of specification version 2025-03-26). The older SSE-only transport has been deprecated.
Why Streamable HTTP?
Supports both SSE streaming and direct HTTP responses
Better session management (stateful or stateless)
Uses standard HTTP methods (GET/POST)
More flexible and scalable than SSE-only transport
This is an educational project demonstrating how to develop and host an OpenAI App on Render. Feel free to use it as a starting point for your own apps!
Key Learning Points:
OpenAI Apps SDK widget development
MCP protocol implementation
Database transactions & data modeling
External API integration (TMDB)
Multi-provider LLM integration
Production deployment patterns
License
MIT License - Applies to this demo code only.
Third-party services: This app uses TMDB, OpenAI, Anthropic, and Google Gemini APIs, each with their own terms. You're responsible for compliance. Movie data provided by TMDB.
Questions? Issues? Open a GitHub issue!
M
Movie Context Provider
render-examples·14 顆星·
An OpenAI App demo built with the OpenAI Apps SDK, that's ready to deploy on Render.