ReelForger LogoDocumentation
Sign inGet Started

MCP Remote Tools (V1)

Page role: this page defines ReelForger MCP V1 as a thin remote tool layer over the existing API.

V1 goals and non-goals

  • Goal: make ReelForger easier for agents to call via a small MCP tool surface.
  • Goal: keep raw ReelForger API endpoints as the source of truth.
  • Non-goal: MCP V1 is not a planning engine. It only exposes execution and validation tools over ReelForger.

Transport and auth

  • Transport: remote HTTP MCP server (POST /mcp JSON-RPC).
  • Endpoint: https://mcp.reelforger.com/mcp
  • Auth (V1): pass-through per-user ReelForger API key.
    • MCP caller sends Authorization: Bearer <REELFORGE_API_KEY>.
    • MCP forwards that same header to ReelForger API.

When to use MCP vs raw API

  • Use MCP for agent/tool-native execution where calling tools is easier than hand-crafting HTTP requests.
  • Use raw API for direct HTTP integrations and lower-level contract control.
  • Raw API remains source of truth; MCP mirrors a focused subset for agent ergonomics.

Tool surface (required)

  1. render_recipe

    • Wraps POST https://api.reelforger.com/v1/recipes/render
    • Input: { request: <exact recipe render body> }
    • Output: { ok, request_id, data: { job_id } }

  2. render_timeline

    • Wraps POST https://api.reelforger.com/v1/videos/render
    • Input: { request: <exact timeline render body> }
    • Output: { ok, request_id, data: { job_id } }

  3. validate_request

    • Explicit use guidance:
      • mode: "timeline": full server validation via POST /v1/videos/validate (no queue, no credits).
      • mode: "recipe": lightweight shape checks only (there is no dedicated recipe validate endpoint in API V1).
    • Input: { mode: "recipe" | "timeline", request: <payload> }
    • Output: { ok, request_id?, data: { mode, validation_scope, ... } }

  4. get_job_status

    • Wraps GET https://api.reelforger.com/v1/jobs/{jobId}
    • Input: { job_id }
    • Output: { ok, request_id, data: <job object> }

Optional tools (non-blocking for V1 launch)

Secondary helper tools:

  • get_supported_patterns
  • get_caption_presets

Both return curated static MCP-side catalogs (not dynamic docs scraping).

Current caveats

  • validate_request with mode: "recipe" is lightweight by design (shape checks only).
  • Full server-side validation parity exists for validate_request with mode: "timeline".
  • OpenAPI and raw API endpoints remain the canonical contract source.

Canonical MCP flow (inline transcription)

When caption words are omitted, ReelForger may transcribe automatically during render:

  1. tools/call → render_recipe
  2. Receive job_id
  3. Poll tools/call → get_job_status until terminal status

Example request/response sequence:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "render_recipe",
    "arguments": {
      "request": {
        "recipe_id": "captioned_clip",
        "style_preset": "karaoke_yellow",
        "variables": {
          "primary_video_url": "https://pub-2ad5592bc4ca44abb609acfc0b7c5ceb.r2.dev/reel-forge-website-assets/talking%20head%20runner.mp4",
          "layout_variant": "full_frame"
        }
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "structuredContent": {
      "ok": true,
      "request_id": "req_abc123",
      "data": {
        "job_id": "8f1fd0fe-63a5-4fef-8f2c-8f1225f6d309"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "get_job_status",
    "arguments": {
      "job_id": "8f1fd0fe-63a5-4fef-8f2c-8f1225f6d309"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "structuredContent": {
      "ok": true,
      "request_id": "req_def456",
      "data": {
        "id": "8f1fd0fe-63a5-4fef-8f2c-8f1225f6d309",
        "status": "completed",
        "output_url": "https://assets.reelforger.com/user_x/job_y.mp4",
        "billing": {
          "transcription_credit_cost": 3,
          "transcription_duration_seconds_billed": 14.6,
          "render_credit_cost": 6,
          "total_credit_cost": 9
        }
      }
    }
  }
}
ReelForger