Friday, August 01, 2025

Building a Model Context Protocol (MCP) Server for Movie Data: A Deep Dive into Modern AI Integration


 

The Challenge: Bringing Movie Data to AI Assistants


As AI assistants become increasingly sophisticated, there's a growing need for them to access real-time, structured data from external APIs. While many AI models have impressive knowledge, they often lack access to current information or specialized databases. This is where the Model Context Protocol (MCP) comes in—a standardized way for AI systems to interact with external data sources and tools.

Today, I want to share my experience building an MCP server that bridges AI assistants with the Open Movie Database (OMDB) API, allowing any MCP-compatible AI to search for movies, retrieve detailed film information, and provide users with up-to-date movie data.

 

What is the Model Context Protocol?

The Model Context Protocol is a emerging standard that enables AI assistants to safely and efficiently interact with external tools and data sources. Think of it as a universal translator that allows AI models to:

  • 🔍 Search external databases
  • 🛠️ Execute specific tools and functions
  • 📊 Retrieve real-time data
  • ⚡ Integrate seamlessly with existing systems

MCP servers act as intermediaries, exposing external APIs through a standardized JSON-RPC interface that AI assistants can understand and interact with safely.

 

The Project: OMDB MCP Server

I decided to build an MCP server for the Open Movie Database (OMDB) API—a comprehensive movie database that provides detailed information about films, TV shows, and series. The goal was to create a production-ready server that would allow AI assistants to:

  1. Search for movies by title, year, and type
  2. Get detailed movie information including plot, cast, ratings, and awards
  3. Lookup movies by IMDB ID for precise identification

 

Technical Architecture

 

Core Technologies

  • Spring Boot 3.5.4 - For the robust web framework
  • Java 21 - Taking advantage of modern language features
  • WebFlux & Reactive WebClient - For non-blocking, asynchronous API calls
  • Maven - For dependency management and build automation
 

MCP Protocol Implementation

The server implements three core MCP endpoints:

 

1. Protocol Handshake (initialize)

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {"name": "ai-client", "version": "1.0.0"}
  }
}
 

2. Tool Discovery (tools/list)

Returns available tools that the AI can use:

  • search_movies
  • get_movie_details
  • get_movie_by_imdb_id
 

3. Tool Execution (tools/call)

Executes the requested tool with provided arguments and returns formatted results.

 

Smart Error Handling

One of the key challenges was implementing robust error handling. The server includes:

  • Input validation for required parameters
  • Graceful API failure handling with meaningful error messages
  • Timeout configuration to prevent hanging requests
  • Detailed logging for debugging and monitoring

 

Real-World Challenges and Solutions

 

Challenge 1: HTTPS Migration

Initially, the OMDB API calls were failing due to (my AI assistant 🤨 ) using HTTP instead of HTTPS. Modern APIs increasingly require secure connections.

Solution: Updated all API calls to use HTTPS and configured the WebClient with proper SSL handling.

 

Challenge 2: DNS Resolution on macOS

Encountered Netty DNS resolution warnings that could impact performance on macOS systems.

Solution: Added the native macOS DNS resolver dependency:

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-resolver-dns-native-macos</artifactId>
    <classifier>osx-aarch_64</classifier>
</dependency>
 

Challenge 3: Response Formatting

Raw OMDB API responses needed to be formatted for optimal AI consumption.

Solution: Created custom formatters that present movie data in a structured, readable format:

private String formatMovieDetails(OmdbMovie movie) {
    StringBuilder sb = new StringBuilder();
    sb.append("🎬 ").append(movie.getTitle()).append(" (").append(movie.getYear()).append(")\n\n");
    
    if (movie.getRated() != null) sb.append("Rating: ").append(movie.getRated()).append("\n");
    if (movie.getRuntime() != null) sb.append("Runtime: ").append(movie.getRuntime()).append("\n");
    // ... additional formatting
    
    return sb.toString();
}
 

Example Usage

Once deployed, AI assistants can interact with the server naturally:

User: "Find movies about artificial intelligence from the 1990s"

AI Assistant (via MCP): Calls search_movies with parameters:

{
  "title": "artificial intelligence", 
  "year": "1990s"
}

Result: Formatted list of AI-themed movies from the 1990s with IMDB IDs for further lookup.

 

Key Features

 

🚀 Production Ready

  • Comprehensive error handling
  • Input validation
  • Configurable timeouts
  • Detailed logging

⚡ Performance Optimized

  • Reactive, non-blocking architecture
  • Connection pooling
  • Efficient memory usage

🔧 Developer Friendly

  • Complete documentation
  • Test scripts included
  • Easy configuration
  • Docker-ready

🌐 Standards Compliant

  • Full MCP 2024-11-05 specification compliance
  • JSON-RPC 2.0 protocol
  • RESTful API design

 

Testing and Validation

The project includes comprehensive testing:

# Health check
curl http://localhost:8080/mcp/health

# Search for movies
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", 
"params": {"name": "search_movies", 
"arguments": {"title": "Matrix"}}}'
 

Lessons Learned

 

1. Protocol Standards Matter

Following the MCP specification exactly ensured compatibility with different AI clients without modification.

2. Error Handling is Critical

In AI integrations, clear error messages help both developers and AI systems understand and recover from failures.

3. Documentation Drives Adoption

Comprehensive documentation with examples makes the difference between a useful tool and one that sits unused.

4. Modern Java is Powerful

Java 21 features like pattern matching and records significantly improved code readability and maintainability.

 

Future Enhancements

The current implementation is just the beginning. Future enhancements could include:

  • Caching layer for frequently requested movies
  • Rate limiting to respect API quotas
  • Additional data sources (e.g., The Movie Database API)
  • Advanced search features (genre filtering, rating ranges)
  • Recommendation engine integration

 

Try It Yourself

The complete source code is available on GitHub: github.com/tyrell/omdb-mcp-server

To get started:

  1. Clone the repository
  2. Get a free OMDB API key from omdbapi.com
  3. Set your API key: export OMDB_API_KEY=your-key
  4. Run: mvn spring-boot:run
  5. Test: curl http://localhost:8080/mcp/health 

 

Conclusion

Building this MCP server was an excellent introduction to the Model Context Protocol and its potential for enhancing AI capabilities. The project demonstrates how modern Java frameworks like Spring Boot can be used to create robust, production-ready integrations between AI systems and external APIs.

As AI assistants become more prevalent, tools like MCP servers will become essential infrastructure—bridging the gap between AI intelligence and real-world data. The movie database server is just one example, but the same patterns can be applied to any API or data source.

The future of AI isn't just about smarter models; it's about giving those models access to the vast ecosystem of data and tools that power our digital world. MCP servers are a key piece of that puzzle.

 

Want to discuss this project or share your own MCP server experiences? Feel free to reach out or contribute to the project on GitHub!

 

Technical Specifications

  • Language: Java 21
  • Framework: Spring Boot 3.5.4
  • Protocol: MCP 2024-11-05
  • API: OMDB (Open Movie Database)
  • Architecture: Reactive, Non-blocking
  • License: MIT
  • Status: Production Ready
 

Repository Structure

omdb-mcp-server/
├── src/main/java/co/tyrell/omdb_mcp_server/
│   ├── controller/     # REST endpoints
│   ├── service/        # Business logic
│   ├── model/          # Data models
│   └── config/         # Configuration
├── README.md           # Complete documentation
├── test-scripts/       # Testing utilities
└── LICENSE             # MIT License
GitHub: https://github.com/tyrell/omdb-mcp-server 
 
 
By at
Labels: , , , , , , , , ,