Reality Defender MCP Server

A Model Context Protocol (MCP) server that provides AI-generated media detection capabilities using the Reality Defender API. This server enables LLMs to analyze images, videos, audio, and text files to determine if they were generated by AI.

Features

• AI Media Detection: Analyze files for AI generation using Reality Defender's advanced detection models
• Multiple Input Methods: Support for both direct URL downloads and user file uploads
• Comprehensive File Support: Images, videos, audio, and text files
• Web Upload Interface: Built-in FastAPI web server for secure file uploads
• Error Handling: Robust error handling with user-friendly messages
• Async Operations: Modern async/await patterns for optimal performance

Getting Started

Prerequisites

• Python 3.12
• UV package and project manager
• Reality Defender API Key

Installation

1. Clone the repository:

git clone https://github.com/Reality-Defender/eng-mcp-server.git

2. Install dependencies:

uv sync

3. Set up environment variables:

export REALITY_DEFENDER_API_KEY="your-api-key-here"

Running the Server

MCP Server Mode

To run the MCP server:

uv run ./src/reality_defender_mcp_server/mcp_server.py

By default, the server also starts a small web server for file uploads. You can disable uploads entirely by setting UPLOADS=false.

To run MCP over Streamable HTTP (cloud-friendly):

FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=8000 uv run ./src/reality_defender_mcp_server/mcp_server.py --transport streamable-http

By default, the Streamable HTTP MCP endpoint is served at /mcp.

Standalone Web Server

To run just the web server component:

uv run ./src/reality_defender_mcp_server/web_server.py [options]

Web server options:

• --debug: Enable debug logging
• --host: Server host (default: 127.0.0.1)
• --port: Server port (default: 8080)
• --upload-dir: Upload directory (default: ./uploads)

MCP Client Configuration

Configure the server in your MCP client, e.g. for Claude Desktop:

{
  "mcpServers": {
    "realitydefender": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/eng-reality-defender-mcp-server",
        "run",
        "python",
        "mcp_server.py"
      ],
      "env": {
        "REALITY_DEFENDER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Configuration

The application uses environment variables for configuration:

Variable	Description	Required	Default
REALITY_DEFENDER_API_KEY	API key for Reality Defender service	Yes	-
DEBUG	Enable debug mode	No	false
WEB_SERVER_HOST	Host for the web server	No	127.0.0.1
WEB_SERVER_PORT	Port for the web server	No	8080
WEB_SERVER_UPLOADS_DIR	Directory for file uploads	No	./uploads
UPLOADS	Enable local file upload workflow; set to false to disable uploads and only allow remote URLs	No	true

API Key Authentication

• By default, the server uses REALITY_DEFENDER_API_KEY from environment variables.
• For cloud deployments, clients can pass a request-scoped Reality Defender key using the X-Api-Key HTTP header.
• If X-Api-Key is present, it is used for that request and takes precedence over REALITY_DEFENDER_API_KEY.
• For security, prefer headers over URL query parameters for API keys.

MCP Tools

The server provides the following MCP tools:

reality_defender_generate_upload_url

Generates a unique upload URL for user file uploads.

Returns: GenerateUploadUrlOutput | Error

reality_defender_get_file_info

Retrieves metadata about an uploaded or downloaded file.

Parameters:

• file_id (string): The file ID to retrieve metadata for

Returns: GetFileInfoOutput | Error

reality_defender_request_file_analysis

Analyzes a file for AI generation using Reality Defender API.

Parameters:

• request (RealityDefenderAnalysisRequest): Analysis request with file path/URL and expected file type

Returns: RealityDefenderAnalysisResponse | Error

Streamable HTTP Deployment

• Use --transport streamable-http to expose MCP over HTTP for cloud deployments.
• Configure bind host/port with FASTMCP_HOST and FASTMCP_PORT.
• Default MCP path is /mcp (configurable via FastMCP settings environment variables).
• Continue using X-Api-Key to pass request-scoped Reality Defender credentials.

Container Publishing

• On pushes to main, GitHub Actions builds the Docker image from Dockerfile.
• The image is published to GitHub Container Registry as ghcr.io/<owner>/eng-mcp-server.
• Published tags include latest, main, and sha-<commit>.

Usage Workflows

User Upload Workflow (Recommended)

1. Generate upload URL using reality_defender_generate_upload_url
2. Direct user to upload file at the provided URL
3. Get file info using reality_defender_get_file_info with the UUID
4. Analyze file using reality_defender_request_file_analysis
5. Present results to user

Direct URL Workflow

1. Analyze file directly using reality_defender_request_file_analysis with URL
2. Get additional file info using reality_defender_get_file_info if needed
3. Present results to user

File Structure

Uploaded and downloaded files are organized as:

uploads/
└── {uuid}/
    ├── blob.{ext}     # Raw file data with proper extension
    └── metadata.json  # File metadata (filename, size, timestamp, MIME type, source)

Development

Code Standards

• Type Hints: Always use type hints for all functions and parameters
• Modern Python: Use Python 3.12 features and syntax (str | None instead of Optional[str])
• Async First: Prefer async/await patterns where possible
• Error Handling: Return union types (SuccessType | Error) instead of raising exceptions
• Pydantic Models: Use Pydantic for all structured data validation

Linting and Type Checking

# Type checking
basedpyright

# Linting and formatting
ruff check .
ruff format .

Running Tests

pytest

API Reference

Web Server Endpoints

• GET / - Service information
• GET /health - Health check
• GET /upload/{uuid} - Upload form for specified UUID
• POST /upload/{uuid} - File upload endpoint
• GET /docs - OpenAPI documentation

Note: If UPLOADS=false, the upload web server is not started and only direct URL analysis is supported. The tools and responses will not suggest uploading files when uploads are disabled.

Response Types

RealityDefenderAnalysisResponse

{
    "status": "ARTIFICIAL" | "AUTHENTIC" | "ANALYZING",
    "score": float,  # Confidence score (0-100)
    "models": [      # Individual model results
        {
            "name": str,
            "status": str,
            "score": float | None
        }
    ],
    "file_id": str | None  # For downloaded files
}

Troubleshooting

• API Key Errors: Verify your REALITY_DEFENDER_API_KEY is valid
• File Upload Issues: Check upload directory permissions and disk space
• Network Errors: Verify internet connectivity for URL downloads
• Port Conflicts: Use --port option to specify different port
• Large Files: Files are limited to 1MB via web interface