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:

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