Filtrix Skills + MCP Setup Guide

You only need one MCP server configuration and one MCP key for both image and video skills. Complete the setup once, then reuse the same flow across your agent clients.

1. Prepare your environment and client.
2. Install Filtrix open-source skills.
3. Create your MCP key in Filtrix AI.
4. Add Filtrix MCP in your client config.
5. Verify tools and run first tasks.

• Node.js 18+ installed.
• An MCP-compatible client: OpenClaw, Claude Code/Desktop, Codex, or Cursor.
• Network access from your client to https://mcp.filtrix.ai/mcp.

Install from GitHub (recommended) or from a local checked-out repository during testing.

npx skills add Filtrix-AI/filtrix-skills

npx -y skills add /absolute/path/to/filtrix-skills --yes

To get your MCP key, you must visit the MCP Keys page in your Filtrix AI account. Keep the key in your client secret/env settings. This key is used for both image and video generation through the same MCP server.

Key page: https://app.filtrix.ai/mcp-keys

Paid usage is required before generation tools can be used. Please complete billing setup at https://app.filtrix.ai/billing

Add this mcpServers entry to your MCP client configuration. Replace <YOUR_FILTRIX_MCP_API_KEY> with your real key.

{
  "mcpServers": {
    "filtrix": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.filtrix.ai/mcp",
        "--header",
        "Authorization:\${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <YOUR_FILTRIX_MCP_API_KEY>"
      }
    }
  }
}

After saving config, restart your client so tools are reloaded.

Run these tool calls in order. If all return valid responses, your setup is ready.

1. get_account_credits
2. generate_image_text
3. generate_video_text
4. get_video_status

The open-source repository currently provides three skills. Use one or combine them in the same agent workflow.

Text-to-image and image editing through Filtrix MCP. Supports gpt-image-1, nano-banana, and nano-banana-2 in one skill.

Core tools / components

• generate_image_text
• edit_image_text
• get_account_credits

When to use

• Use gpt-image-1 as the default quality route.
• Use nano-banana for faster iteration loops.
• Use nano-banana-2 for resolution/search/enhance controls.

Text-to-video, image-to-video, status polling, and final download flow via Filtrix MCP task APIs.

Core tools / components

• generate_video_text
• generate_video_image
• get_video_status

When to use

• Text-to-video starts an async task and returns a request_id.
• Image-to-video supports grok-imagine and seedance-1-5-pro.
• Use get_video_status to drive your agent polling loop.

Prompt-design framework for stable motion language, camera grammar, and @asset tagging before you run video generation.

Core tools / components

• Prompt templates
• Motion grammar
• Stability checklist

When to use

• No MCP call required for this skill.
• Best used as a planning layer before video generation.
• Includes templates and examples for consistent cinematic motion.

For quick success, call generate_image_text first. Then use edit_image_text for iterative refinement.

{
  "tool": "generate_image_text",
  "arguments": {
    "prompt": "A cinematic portrait, dramatic side lighting",
    "mode": "gpt-image-1",
    "size": "1024x1536",
    "idempotency_key": "img-quickstart-001"
  }
}

python scripts/generate.py \
  --prompt "a cinematic portrait, dramatic lighting" \
  --mode gpt-image-1 \
  --size 1024x1536

python scripts/edit.py \
  --prompt "replace background with a rainy Tokyo street" \
  --image-url https://example.com/input.png \
  --mode nano-banana-2 \
  --size 1024x1024 \
  --resolution 2K \
  --enhance-mode

Video generation is async. Submit with generate_video_text or generate_video_image, then poll get_video_status until completion.

{
  "tool": "generate_video_text",
  "arguments": {
    "prompt": "A white sports car drifting through a rainy Tokyo intersection",
    "aspect_ratio": "16:9",
    "idempotency_key": "vid-quickstart-001"
  }
}

{
  "tool": "get_video_status",
  "arguments": {
    "request_id": "<REQUEST_ID_FROM_GENERATE_VIDEO_TEXT>"
  }
}

python scripts/generate.py \
  --mode text-to-video \
  --prompt "a cinematic drone shot over a neon city at night" \
  --aspect-ratio 16:9 \
  --wait

python scripts/status.py \
  --request-id YOUR_REQUEST_ID \
  --download \
  --output /tmp/video.mp4

• 401 Unauthorized: MCP key is invalid, revoked, or not injected into AUTH_HEADER.
• 402 Insufficient credits: Add credits in Filtrix AI, then retry the task.
• 409 Duplicate idempotency key: Use a new idempotency_key for new generation intents.
• 400 Invalid arguments: Check required parameters and enum values in your tool call.

Best practice: keep idempotency keys unique per intent to avoid duplicate billing and unstable loops.

A complete Markdown version of this guide is available for agent context loading and prompt injection.