Content
# fal-mpc
> A general-purpose [Model Context Protocol](https://modelcontextprotocol.io) server that puts the full power of **[fal.ai](https://fal.ai)** inside any MCP client.
[fal.ai](https://fal.ai) is a generative-media powerhouse — **600+ image, video, audio, and text models** (FLUX, Kontext, Veo, Kling, Suno-style audio, and more) served on some of the fastest inference infrastructure in the industry. This server hands that entire catalog to an MCP client (Claude Code, Claude Desktop, Cursor, etc.) through a small, clean set of tools: run any model by id, manage the async job queue, browse and search the model catalog, and inspect a model's exact input schema before calling it.
## Why fal.ai
- **Breadth that's hard to beat.** One API key unlocks 600+ production models across every generative modality — no per-vendor integrations, no juggling SDKs.
- **Built for speed.** fal's inference stack is engineered for low-latency generation, so fast models return in seconds and heavy jobs stream through a robust async queue.
- **Always current.** New state-of-the-art models land on fal continuously — pointing this server at a new `model_id` is all it takes to use them.
- **Schema-first, no guesswork.** Every model publishes an OpenAPI schema, so `fal_get_model_schema` lets your agent discover exact inputs and defaults instead of guessing.
- **Agent-friendly by design.** A predictable REST surface and a clean queue model make fal a natural fit for autonomous, multi-step generative workflows.
This MCP server is a thin, faithful bridge to that platform — it stays out of the way and lets fal.ai shine.
## Tools
| Tool | Purpose |
|---|---|
| `fal_run_model` | Run a model synchronously and block for the result (best for fast models, <2 min) |
| `fal_submit_request` | Submit a job to the async queue and get a `request_id` back immediately (best for video/training) |
| `fal_check_status` | Poll a queued request's status (`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`) |
| `fal_get_result` | Fetch the final output of a completed queued request |
| `fal_cancel_request` | Cancel a request that's still `IN_QUEUE` |
| `fal_list_models` | Search/browse the fal.ai model catalog to find the right model id |
| `fal_get_model_schema` | Fetch a model's OpenAPI schema — exact input fields, types, defaults |
| `fal_encode_file_as_data_uri` | Locally base64-encode a file so it can be passed as an `image_url`-style argument without a separate upload step |
## Setup
1. Get an API key from [fal.ai/dashboard/keys](https://fal.ai/dashboard/keys).
2. Build the server:
```bash
npm install
npm run build
```
3. Add it to your MCP client config (e.g. Claude Code's `.mcp.json` or Claude Desktop's config), pointing at `dist/index.js` and setting `FAL_KEY`:
```json
{
"mcpServers": {
"fal": {
"command": "node",
"args": ["/absolute/path/to/fal-mpc/dist/index.js"],
"env": {
"FAL_KEY": "your-fal-api-key"
}
}
}
}
```
## Typical workflows
**Quick image generation:**
```
fal_run_model(model_id="fal-ai/flux/dev", arguments={"prompt": "a sunset over mountains"})
```
**Not sure what a model accepts?**
```
fal_get_model_schema(model_id="fal-ai/flux-pro/kontext")
```
**Slow model (video) — fire and check back later:**
```
fal_submit_request(model_id="fal-ai/minimax/video-01", arguments={"prompt": "a rocket launch"})
-> fal_check_status(model_id=..., request_id=...)
-> fal_get_result(model_id=..., request_id=...) # once COMPLETED
```
**Using a local image as input:**
```
fal_encode_file_as_data_uri(file_path="/path/to/photo.jpg")
-> pass the returned data: URI as image_url in fal_run_model / fal_submit_request
```
**Find a model for a task:**
```
fal_list_models(query="background removal")
```
## Notes
- Base64 data URIs work directly as file inputs anywhere fal expects a URL — `fal_encode_file_as_data_uri` handles this locally (no fal upload API call needed). For files already hosted publicly, just pass the URL directly.
- `fal_run_model` has a 5-minute timeout; anything slower should go through `fal_submit_request`.
- All tools support `response_format: "json"` for structured output or `"markdown"` (default) for readability.
## Evaluation
`evaluation.xml` contains 10 read-only QA pairs testing `fal_get_model_schema` against known model defaults. Run with the harness described in the mcp-builder skill's evaluation guide. Since fal.ai model schemas can change as models are updated, spot-check these against the live API before relying on them.
