Http Server

An HTTP-based MCP (Model Context Protocol) server that provides film discovery capabilities by connecting to a deployed LangGraph agent. This server supports both MCP protocol and direct HTTP API access, making it suitable for serverless deployment and integration with various AI assistants.

Features

• HTTP MCP Protocol Support: Full MCP protocol implementation over HTTP
• Direct HTTP API: REST endpoints for non-MCP clients
• Film Discovery Tool: Find films using natural language descriptions
• Remote LangGraph Integration: Connects to deployed discovery agent service
• Serverless Ready: Deploy to Vercel, AWS Lambda, Cloudflare Workers
• CORS Enabled: Web client compatibility
• Auto-generated OpenAPI docs: Available at /docs

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Environment Setup

cp .env.example .env

Edit .env with your configuration:

LANGGRAPH_API_KEY="your_actual_api_key_here"
DISCOVERY_AGENT_URL="your_agent_url_here"
PORT=8050

# HTTPS Configuration (required for Claude Desktop)
ENABLE_HTTPS=true
SSL_CERTFILE="/path/to/your/certificate.pem"
SSL_KEYFILE="/path/to/your/private_key.pem"
# Optional: SSL_CA_CERTS="/path/to/ca_bundle.pem"
# Optional: SSL_CERT_REQS=1

3. Run the Server

python server.py

The server will be available at http://localhost:8050 (HTTP) or https://localhost:8050 (HTTPS)

API Endpoints

MCP Protocol Endpoints

• POST /mcp: Main MCP protocol handler
• GET /tools: List available MCP tools

Direct HTTP Endpoints

• POST /discover-film: Film discovery endpoint
• GET /server-info: Server information
• GET /health: Health check
• GET /: Server overview
• GET /docs: Interactive API documentation

Usage Examples

MCP Protocol (for AI assistants)

POST /mcp
{
  "method": "tools/call",
  "params": {
    "name": "discover_film",
    "arguments": {
      "film_description": "to eternity and beyond"
    }
  }
}

Direct HTTP API

curl -X POST "http://localhost:8050/discover-film" \
  -H "Content-Type: application/json" \
  -d '{
    "film_description": "to eternity and beyond"
  }'

SSL Certificate Setup (For HTTPS)

Option 1: Self-Signed Certificates (For Development)

Generate a self-signed certificate for local development:

# Create SSL directory
mkdir ssl

# Generate private key
openssl genrsa -out ssl/private_key.pem 2048

# Generate self-signed certificate
openssl req -new -x509 -key ssl/private_key.pem -out ssl/certificate.pem -days 365 -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"

# Update your .env file
echo "SSL_CERTFILE=ssl/certificate.pem" >> .env
echo "SSL_KEYFILE=ssl/private_key.pem" >> .env

Note: You'll need to accept the security warning in your browser for self-signed certificates.

Option 2: Let's Encrypt (For Production)

For production deployments, use Let's Encrypt or another certificate authority:

# Install certbot
sudo apt-get install certbot

# Generate certificate for your domain
sudo certbot certonly --standalone -d your-domain.com

# Update .env with Let's Encrypt paths
echo "SSL_CERTFILE=/etc/letsencrypt/live/your-domain.com/fullchain.pem" >> .env
echo "SSL_KEYFILE=/etc/letsencrypt/live/your-domain.com/privkey.pem" >> .env

Option 3: Existing Certificates

If you have existing SSL certificates, simply point to them in your .env:

SSL_CERTFILE="/path/to/your/certificate.pem"
SSL_KEYFILE="/path/to/your/private_key.pem"

Claude Desktop Configuration

For local Claude Desktop integration, add to claude_desktop_config.json:

HTTPS (Required for Claude Desktop):

{
  "mcpServers": {
    "film-discovery-http": {
      "url": "https://localhost:8050/mcp",
      "type": "http"
    }
  }
}

HTTP (For testing only - not supported by Claude Desktop):

{
  "mcpServers": {
    "film-discovery-http": {
      "url": "http://localhost:8050/mcp",
      "type": "http"
    }
  }
}

Serverless Deployment

Vercel

vercel deploy

AWS Lambda (with Serverless Framework)

# serverless.yml
service: mcp-discovery-server
provider:
  name: aws
  runtime: python3.12
functions:
  api:
    handler: server.handler
    events:
      - http:
          path: /{proxy+}
          method: ANY

Cloudflare Workers

Deploy using Cloudflare's Python Workers (when available) or create a Node.js wrapper.

Docker Deployment

docker build -t mcp-discovery-server .
docker run -p 8050:8050 --env-file .env mcp-discovery-server

Integration Examples

ChatGPT Custom Actions

Use the OpenAPI schema from /docs to create ChatGPT custom actions:

{
  "openapi": "3.0.0",
  "servers": [{"url": "https://your-deployed-server.com"}],
  "paths": {
    "/discover-film": {
      "post": {
        "operationId": "discoverFilm",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DiscoverFilmRequest"
              }
            }
          }
        }
      }
    }
  }
}

Web Applications

// JavaScript example
const response = await fetch('https://your-server.com/discover-film', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    film_description: 'to eternity and beyond'
  })
});
const result = await response.json();

Response Format

Successful Response

{
  "success": true,
  "data": {
    "film_id": "123",
    "film_name": "An Inconvenient Truth",
    "film_directors": "Davis Guggenheim",
    "film_publish_year": 2006,
    "film_page_url": "https://example.com/film/123",
    "film_reasoning": "This film effectively describes...",
    "dataset_download": "false"
  },
  "message": "Film discovery completed successfully"
}

Error Response

{
  "success": false,
  "error": "Request timeout",
  "message": "Film discovery request timed out after 60 seconds"
}

Configuration

Environment Variable	Default	Description
LANGGRAPH_API_KEY	-	Required: LangGraph API key
DISCOVERY_AGENT_URL	(deployed URL)	LangGraph agent endpoint
PORT	8050	HTTP server port
ENABLE_HTTPS	false	Enable HTTPS/SSL support
SSL_CERTFILE	-	Path to SSL certificate file (required if HTTPS enabled)
SSL_KEYFILE	-	Path to SSL private key file (required if HTTPS enabled)
SSL_CA_CERTS	-	Optional: Path to CA certificate bundle
SSL_CERT_REQS	-	Optional: SSL certificate verification mode

Architecture

Client → HTTP MCP Server → LangGraph Cloud Agent → Film Database

The HTTP server provides both MCP protocol compatibility and direct REST API access, making it suitable for various integration scenarios while maintaining compatibility with MCP-aware AI assistants.

Development

Run with auto-reload

uvicorn server:app --reload --host 0.0.0.0 --port 8050

View API Documentation

Visit http://localhost:8050/docs for interactive Swagger UI documentation.

Testing

HTTP (Development):

# Health check
curl http://localhost:8050/health

# List tools
curl http://localhost:8050/tools

# Test film discovery
curl -X POST http://localhost:8050/discover-film \
  -H "Content-Type: application/json" \
  -d '{"film_description": "test"}'

HTTPS (Production/Claude Desktop):

# Health check (with self-signed certificate)
curl -k https://localhost:8050/health

# List tools
curl -k https://localhost:8050/tools

# Test film discovery
curl -k -X POST https://localhost:8050/discover-film \
  -H "Content-Type: application/json" \
  -d '{"film_description": "test"}'

Note: The -k flag is used to ignore certificate warnings for self-signed certificates.