# Filtrix Skills + MCP Setup Guide

Source: https://github.com/Filtrix-AI/filtrix-skills
MCP endpoint: https://mcp.filtrix.ai/mcp

## Compatible Clients

- OpenClaw
- Claude Code
- Codex
- Cursor

## Get Started

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.

### Quick Start Path

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.

## 1. Prerequisites

- 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.

## 2. Install Filtrix Skills

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

### Install from GitHub
```bash
npx skills add Filtrix-AI/filtrix-skills
```

### Install from local path
```bash
npx -y skills add /absolute/path/to/filtrix-skills --yes
```

## 3. Create Your MCP Key

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
Billing page: https://app.filtrix.ai/billing
Paid usage is required before generation tools can be used. Please complete billing setup at https://app.filtrix.ai/billing

## 4. Connect Filtrix MCP in Your Client

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

```json
{
  "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>"
      }
    }
  }
}
```

## 5. Verify Setup

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

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

## Skills Directory

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

### filtrix-image-gen

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.

### filtrix-video-gen

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.

### seedance-2-0-prompting-skills

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.

## First Image Task

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

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

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

### Script mode: scripts/edit.py
```bash
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
```

## First Video Task

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

### Tool call: generate_video_text
```json
{
  "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 call: get_video_status
```json
{
  "tool": "get_video_status",
  "arguments": {
    "request_id": "<REQUEST_ID_FROM_GENERATE_VIDEO_TEXT>"
  }
}
```

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

### Script mode: scripts/status.py
```bash
python scripts/status.py \
  --request-id YOUR_REQUEST_ID \
  --download \
  --output /tmp/video.mp4
```

## Troubleshooting

- 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.