@thenavidm/fal-ai-mcp-cli

v3.0.1

Published

15 days ago

fal.ai shared MCP and task CLI for current models, queue receipts, asset management, private accounts and exact approved generation batches.

fal.ai MCP Server & CLI

fal.ai MCP server and CLI for Codex and AI agents. 66 shared tools for current models, queue receipts, Assets and storage controls, private account profiles and exact reviewed generation batches.

One package provides a task CLI, local stdio MCP and versioned desktop bundle. Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI. Complete setup: navid.me.

The terminal illustrates actual commands, not a recorded provider account session. Node 22+ is required for manual installs; private account access, model eligibility and generation credits remain separate.

Two ways to use it

Command line

A terminal or shell agent calls only the requested task.

npx -y --package @thenavidm/fal-ai-mcp-cli@latest fal-ai-cli search-models --limit 1 --agent

MCP server, for your AI app

codex mcp add fal-ai --env FAL_TOKEN_FILE=/absolute/private/fal.txt -- npx -y @thenavidm/fal-ai-mcp-cli@latest

Which one

Use the CLI for task-specific shell discovery/compact selected output, or MCP for an AI client supporting local tools. Both enforce the same handlers, validation and approval policy.

Features

Current dynamic model/schema discovery, receipt-based queue operations and full native creative platform arguments.
Shared local confirmation/read-only policy and isolated account API keys.
Exact current-schema/unit-quote batch review and stop-on-failure receipts.
Native Assets, collection, tag, character and CDN ACL/retention controls.
Complete Codex/client/OS/desktop setup, current comparisons, version history and accordion FAQs.

| Section | What it covers | | --- | --- | | 1. What you can ask it | What you can ask it | | 2. Quick install | Quick install | | 3. Set up fal.ai access | Set up fal.ai access | | 4. Connect your client | Connect your client | | 5. Check it works | Check it works | | 6. Output, flags and exit codes | Output, flags and exit codes | | 7. MCP or CLI and token cost | MCP or CLI and token cost | | 8. Every tool and argument | Every tool and argument | | 9. Model and asset workflows | Model and asset workflows | | 10. Exact reviewed batches and pagination | Exact reviewed batches and pagination | | 11. Several private accounts | Several private accounts | | 12. Writing safely | Writing safely | | 13. How the two surfaces work | How the two surfaces work | | 14. Your data | Your data | | 15. Environment variables | Environment variables | | 16. Updates and removal | Updates and removal | | 17. Troubleshooting | Troubleshooting | | 18. API coverage and comparisons | API coverage and comparisons | | 19. Versions and migration | Versions and migration | | 20. FAQ | FAQ |

1. What you can ask it

Find exact current image, video, audio or 3D endpoint IDs and inspect their native schemas.
Read unit pricing, estimate quantities deliberately and inspect the intended account's billable usage.
Submit only the approved native model payload, keep its request ID and read progress/results once.
Review several ordered generations against current schemas and prices, then submit only that matching approved batch.
Browse and manage requested Assets, collections, tags and characters using native fields.
Read or explicitly change CDN ACL/retention settings and save a signed access URL privately.

Actual shared discovery exposes 66 tools: 32 reads and 34 confirmed operations. It wraps 53 selected current native platform operations plus 13 creative/account/batch helpers. All nine legacy tool names remain, with deliberate 2.0 breaking argument/behavior corrections documented below. Generic model support is conditional on discoverable/compilable current JSON schemas, credentials and model access; it is not a guarantee that every current/future endpoint works.

2. Quick install

npm install -g @thenavidm/fal-ai-mcp-cli@latest
fal-ai-cli --version
fal-ai-cli tools
fal-ai-cli schema submit-job
fal-ai-cli login

Node 22+ for manual CLI/local MCP. INSTALL.md covers every declared client/OS and the versioned desktop bundle. Official genmedia and Python fal are separate binaries; ours is fal-ai-cli.

3. Set up fal.ai access

Private account access

Sign into the intended fal account. Confirm which personal/team account owns the credits and key before creating or copying it.
Use only the provider permissions needed for the requested work. Model execution, Assets, billing and organization reads have different requirements. A working model read does not prove asset/admin permissions.
Store FAL_KEY in private user/client environment settings or FAL_TOKEN_FILE as an absolute token-only file outside Git. On macOS/Linux use an owner-private directory and regular non-symlink 0600 file, at most 64 KiB. On Windows restrict ACLs to yourself; POSIX mode does not prove Windows ACLs.
Run fal-ai-cli doctor for local settings; doctor --network deliberately reads one model with limit=1. It reports count only, does not spend credits and does not prove the authenticated owner. Public model discovery can work without a key.
Inspect the exact current model schema and unit pricing before approving generation. Use a queue receipt to read progress/results; never submit again to check progress. Do not generate paid media, create keys or delete assets just to test installation.

FAL_ACCOUNTS is a private JSON array of unique {name,api_key,token_file} profiles; FAL_DEFAULT_ACCOUNT selects an exact label. A selected token file overrides only that profile's key. Explicit profiles never inherit FAL_KEY or another profile after missing credentials or a 401/403. Labels are not verified fal owners. Tokens cache until process restart; rotate/revoke at fal and restart clients.

This wrapper uses API keys with Authorization: Key on fixed api.fal.ai, queue.fal.run, fal.run and the SDK-pinned rest.fal.ai upload-initiation origin. No credential goes on the CDN upload PUT. No hosted OAuth, .env loading, SDK key-ID/secret environment inheritance, official genmedia config import, session cookie import, telemetry or automatic background update exists. login prints setup instructions and does not save credentials or start sign-in.

Official account connections

The current model-generation MCP uses OAuth at https://mcp.fal.ai/mcp-relay. Its Active MCP account setting routes new uploads/generations; old jobs remain with their original account, and failed selected-account access does not fall back to personal credits. This is already an official isolation feature. API-key clients, including this package and genmedia, use the key's owning account separately.

The separate Platform MCP at https://api.fal.ai/v1/mcp/platform uses API keys and is read-only account/serverless tooling. Documentation MCP at https://fal.ai/docs/mcp searches public docs without model execution. The old March launch article/key-based endpoint and its nine tools are historical evidence, not the current OAuth setup or tool count.

Costs and permissions

The AGPL wrapper is free; fal generation credits, endpoint pricing, output quantities, model eligibility and concurrency limits apply. Unit pricing and cost estimates are different from completed billable usage. Unit quotes can scale with resolution, duration, output count or GPU time; a batch of ten requests is not a ten-output or ten-dollar limit. No local budget guarantee or credit reservation is promised.

No requests automatically retry, including reads, 429, failed uploads, timeouts or 5xx. Respect current provider throttling guidance before deliberately repeating a read. A timeout after a paid POST may have spent credits without returning a request ID: inspect fal history before another submission. Responses cap at 5 MiB and JSON requests at 1 MiB. One native list page is returned with its real cursor; there is no invented all-pages backup.

Data and file controls

Generated and uploaded CDN media may be public under account defaults. The local generation default sends X-Fal-Store-IO:0 to disable provider JSON input/output storage; CDN media access and expiration are separate. Explicit store_io:true allows native payload storage. Native lifecycle JSON can specify expiration_duration_seconds and initial_acl with default allow/forbid/hide and nickname rules. Unknown nicknames may be silently dropped by fal; an ACL request is not proof of actual external visibility.

Local upload sends only the selected regular file, 1 byte–20 MiB, through upload initiation and one restricted fal.media PUT. Larger/multipart/remote-URL upload conveniences belong to the official clients; no retry or automatic generation occurs here. Sign-file URL credentials are saved only into an exclusive new private JSON file. Existing files are never overwritten. Keep parent directory and Windows ACLs private; a signature is access authority even if its field says URL.

Rotation and revocation

Revoke the exact key at fal, replace private settings/files and restart every process. Revoke official OAuth connections separately. Removing the package/client registration does not cancel jobs, undo asset mutations, delete provider payloads/CDN files, revoke credentials or refund generation credits. Inspect receipts and provider state before explicitly requested cleanup.

4. Connect your client

Codex setup comes first in INSTALL.md, followed by Claude Code, Claude Desktop extension/manual stdio, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Cline, Docker and other local stdio clients on macOS/Windows/Linux. Use private key settings available to the actual local/remote runtime. GUI apps may not inherit terminal environment; restart after changing settings.

This package provides local stdio. Remote-only clients use the provider-hosted OAuth relay. Skills are optional agent guidance; installing npm does not register SKILL.md automatically. No Claude Code installation is needed for Codex.

codex mcp add fal-ai --env FAL_TOKEN_FILE=/absolute/private/fal.txt -- npx -y @thenavidm/fal-ai-mcp-cli@latest

5. Check it works

fal-ai-cli --version
fal-ai-cli tools
fal-ai-cli list-accounts --agent
fal-ai-cli doctor
fal-ai-cli doctor --network
fal-ai-cli search-models --limit 1 --agent
fal-ai-cli get-model-info --model-id fal-ai/flux/dev --agent

Public model discovery/schema reads have been verified without credentials or generation credits. Private doctor --network reads one model with count only; model metadata can be public, so that result is not an account-owner or all-permissions test. Model runs, authenticated Assets and real queue outcomes require separate live-account verification. Never use a paid or destructive call as an install smoke test.

6. Output, flags and exit codes

Both surfaces return provider JSON through the same handlers. Queue submission returns request_id receipts with completed:false. get_job_status and get_job_result read once; cancel receipts do not prove stopped processing/refunds. Synchronous run timeouts can leave an unknown paid outcome. No returned media is downloaded or embedded automatically. Signed access credentials go only to a new exclusive private file; console responses contain saved-file metadata.

Use the actual task schema. Repeated primitive array flags pass one value each; repeated --tasks values are individual JSON task objects. Complete native body unions use --payload JSON or a private --payload-file, mutually exclusive with flat body flags. Native query/header/body names remain visible in the schema; kebab-case flags come from the shared house bridge.

fal-ai-cli search-models --limit 5 --agent --select models,next_cursor
fal-ai-cli submit-job --help
fal-ai-cli schema estimate-pricing

| Flag | Behavior | | --- | --- | | --agent | Compact JSON and no prompts; never confirms a write | | --confirm | Explicit approval for exactly the requested operation | | --account LABEL | Exact private API-key profile | | --select a,b.c | Local output field selection | | --payload / --payload-file | Native body, mutually exclusive with other body routes | | --tasks JSON | Repeat an individual ordered generation object | | --review-sha256 HASH | Exact preview hash before batch submission | | --output-file PATH | New private signed-URL credential file |

| Exit | Meaning | | --- | --- | | 0 | Handler success/receipt; submission does not mean completed generation | | 1 | Unexpected error | | 2 | Invalid input or refused policy operation, an unknown command or a hidden write | | 3 | Not found | | 4 | Provider authentication/permissions | | 5 | Provider/network/unknown outcome | | 7 | Rate limit | | 10 | Missing or invalid local account credentials/configuration |

7. MCP or CLI and token cost

The tools, schemas, handlers and write guard are shared. MCP clients discover local tools; shell agents can inspect command help/schema only when needed and select smaller result fields. Context cost depends on client tool discovery, loaded descriptions/schemas, prompts and output size.

Measured on 2026-10-05 against 2.0.2, the same day, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, the difference read from the API's own usage figures) and Codex 0.159.3 on gpt-6.1-sol:

| Cost | 2.0.2 | 3.0.0 | | --- | --- | --- | | Claude Code, every tool loaded, every message | 41,570 | 40,519 | | Claude Code's default, tool search, every message | 1,316 | 1,319 | | SKILL.md, read once | 1,290 | 1,340 | | Codex over the CLI, one task, median of five | 127,484 | 105,371 | | Codex over MCP, the same task, median of five | 77,462 | 77,596 |

The task was "find the command that estimates what a generation will cost, and the flags it requires". Over the CLI, three 2.0.2 runs guessed an estimate command that does not exist, because 2.0.2's help listed none, and every extra step carries the whole conversation forward; every 3.0.0 run asked which. Over MCP, Codex prints its own TypeScript rendering of the tool list and keeps its first and last 20,000 characters or so: the whole rendering is 532 tokens shorter on 3.0.0, but the part Codex keeps holds about 57 more, which each later request carries. SKILL.md costs 50 more because it now says how approval works over MCP and lists every exit code.

Tool-list bytes or characters divided by four are not API usage, and no other offering was measured.

8. Every tool and argument

`search_models`

Unified endpoint for discovering model endpoints. Supports three usage modes: 1. List Mode (no parameters): Paginated list of all available model endpoints with minimal metadata. 2. Find Mode (endpoint_id parameter): Retrieve specific model endpoint(s) by ID. Supports single or multiple IDs. 3. Search Mode (search parameters): Filter models by free-text query, category, or status. Expansion: Use expand to include additional data in each model object: - openapi-3.0 : full OpenAPI 3.0 schema in the openapi field - enterprise_status : enterprise readiness status (ready or pending) in the enterprise_status field Examples of endpoint_id values: - fal-ai/flux/dev - fal-ai/wan/v2.2-a14b/text-to-video - fal-ai/minimax/video-01/image-to-video - fal-ai/hunyuan3d-v21 See fal.ai Model APIs for more details. Authentication: Optional. Providing an API key grants higher rate limits. Common Use Cases: - Browse available models for integration - Retrieve metadata for specific endpoints - Search for models by category or keywords - Get OpenAPI schemas for code generation - Build model selection interfaces

Policy: Read/helper; no explicit mutation approval.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`get_pricing`

Returns unit pricing for requested endpoint IDs. Most models use output-based pricing (e.g., per image/video with proportional adjustments for resolution/length). Some models use GPU-based pricing depending on architecture. Values are expressed per model's billing unit in a given currency. Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status. Common Use Cases: - Display pricing in user interfaces - Compare pricing across different models - Build cost estimation tools - Check current billing rates See fal.ai pricing for more details.

Policy: Read/helper; no explicit mutation approval.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | endpoint_id | Yes | JSON | Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2 | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

`estimate_pricing`

Computes cost estimates using one of two methods: 1. Historical API Price (historical_api_price): - Based on historical pricing per API call from past usage patterns - Takes call_quantity (number of API calls) per endpoint - Useful for estimating based on actual historical usage patterns - Example: "How much will 100 calls to flux/dev cost?" 2. Unit Price (unit_price): - Based on unit price × expected billing units from pricing service - Takes unit_quantity (number of billing units like images/videos) per endpoint - Useful when you know the expected output quantity - Example: "How much will 50 images from flux/dev cost?" Authentication: Required. Users must provide a valid API key. Custom pricing or discounts may be applied based on account status. Common Use Cases: - Pre-calculate costs for batch operations - Display cost estimates in user interfaces - Budget planning and cost optimization See fal.ai pricing for more details.

Policy: Read/helper; no explicit mutation approval.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. | | payload | No; body/guard requirements still apply | JSON | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: 1. |

input.payload

input.payload oneOf branch 1

| Argument | Required | Type | Details | | --- | --- | --- | --- | | estimate_type | Yes | string | Estimate type: historical API pricing based on past usage patterns enum: ["historical_api_price"]. | | endpoints | Yes | object | Map of endpoint IDs to call quantities |

input.payload.oneOf1.endpoints

input.payload.oneOf1.endpoints.{key}

| Argument | Required | Type | Details | | --- | --- | --- | --- | | call_quantity | Yes | integer | Number of API calls to estimate (regardless of units per call) minimum: 1. |

input.payload oneOf branch 2

| Argument | Required | Type | Details | | --- | --- | --- | --- | | estimate_type | Yes | string | Estimate type: unit price calculation based on billing units enum: ["unit_price"]. | | endpoints | Yes | object | Map of endpoint IDs to unit quantities |

input.payload.oneOf2.endpoints

input.payload.oneOf2.endpoints.{key}

| Argument | Required | Type | Details | | --- | --- | --- | --- | | unit_quantity | Yes | number | Number of billing units expected (e.g., number of images, videos, etc.) minimum: 1e-06. |

`get_usage`

Returns paginated usage records for your workspace with filters for endpoint, user, date range, and auth method. Each item includes the billed unit quantity, the pre-discount unit price and cost_subtotal, any percentage discount applied, and the final cost_total (cost_subtotal − cost_discount). Key Features: - Usage data for all endpoints or filtered by specific endpoint(s) - Flexible date range filtering - User-specific usage tracking - Detailed usage line items with unit quantity, price, and discount breakdown - Paginated results for large datasets Common Use Cases: - Generate usage reports for all endpoints or specific models - Track usage patterns - Monitor endpoint usage across different auth methods - Build usage dashboards and visualizations See fal.ai docs for more details.

Policy: Read/helper; no explicit mutation approval.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | limit | No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: 1. | | cursor | No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. | | start | No; body/guard requirements still apply | JSON | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. | | end | No; body/guard requirements still apply | JSON | End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time. | | timezone | No; body/guard requirements still apply | string | Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. default: "UTC". | | timeframe | No; body/guard requirements still apply | string | Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d). enum: ["minute", "hour", "day", "week", "month"]. | | bound_to_timeframe | No; body/guard requirements still apply | string | Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided. enum: ["true", "false"]. default: "true". | | endpoint_id | No; body/guard requirements still apply | JSON | Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2 | | api_key_id | No; body/guard requirements still apply | JSON | Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2 | | login_username | No; body/guard requirements still apply | JSON | Filter by team member login username(s) (nickname). Accepts 1-50 usernames. Supports comma-separated values: ?login_username=alice,bob or array syntax: ?login_username=alice&login_username=bob | | expand | No; body/guard requirements still apply | JSON | Data to include in the response. Use 'time_series' for time-bucketed data, 'summary' for aggregate statistics, 'auth_method' to include a formatted authentication method label, and 'auth_method_structured' to include a machine-readable auth method object (detail, api_key_id, login_username). At least one of 'time_series' or 'summary' is required. default: ["time_series"]. | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |

input.start

input.start anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.start anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.end

input.end anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.end anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.api_key_id

input.api_key_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.api_key_id anyOf branch 2

input.api_key_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.login_username

input.login_username anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.login_username anyOf branch 2

input.login_username.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`get_analytics`

Time-bucketed metrics per model endpoint, including request counts, success/error rates, and latency percentiles. prepare_duration reflects queue/prepare time before execution; duration is request execution time. Use with the Queue/Webhooks flow to monitor SLAs. Metric Selection: You must specify which metrics to include using the expand query parameter. Only requested metrics will be populated in the response, allowing you to optimize query performance and data transfer. Available Metrics: The expand parameter accepts these values, grouped by category: Volume - request_count: Total number of requests in the time bucket - success_count: Successful requests (2xx responses) - user_error_count: User errors (4xx responses) - error_count: Server errors (5xx responses) Error type breakdown - startup_error_count: Startup errors (startup timeout, scheduling failure) - connection_error_count: Connection errors (timeout, disconnected, refused) - timeout_error_count: Request timeout errors - runtime_error_count: Runtime errors (internal error, server error) Queue / prepare latency - p50_prepare_duration, p75_prepare_duration, p90_prepare_duration, p95_prepare_duration, p99_prepare_duration: Time from request submission until execution starts Request execution latency - p25_duration, p50_duration, p75_duration, p90_duration, p95_duration, p99_duration: Time spent processing the request Cold boot - cold_boot_count: Requests with cold boot (startup > 1s) - p50_cold_boot_duration, p75_cold_boot_duration, p90_cold_boot_duration: Cold boot duration percentiles Billing - total_billable_duration: Aggregate billed execution time Key Features: - Selective metric inclusion via expand parameter - Performance metrics (latency percentiles, duration stats) - Reliability metrics (success/error rates, request counts) - Error type breakdown (startup, connection, timeout, runtime) - Cold boot metrics (count, latency percentiles) - Billing duration tracking - Time-bucketed data for trend analysis - Single or multi-model analytics - Flexible date range and timeframe options Common Use Cases: - Monitor model performance and reliability - Generate performance dashboards - Analyze latency trends and patterns - Track error rates and success metrics See Queue API docs for more details.

Policy: Read/helper; no explicit mutation approval.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | limit | No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: 1. | | cursor | No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. | | start | No; body/guard requirements still apply | JSON | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. | | end | No; body/guard requirements still apply | JSON | End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time. | | timezone | No; body/guard requirements still apply | string | Timezone for date aggregation and boundaries. All timestamps in responses are in UTC, but this controls how dates are bucketed. default: "UTC". | | timeframe | No; body/guard requirements still apply | string | Aggregation timeframe for timeseries data (auto-detected from date range if not specified). Auto-detection uses: minute (<2h), hour (<2d), day (<64d), week (<183d), month (>=183d). enum: ["minute", "hour", "day", "week", "month"]. | | bound_to_timeframe | No; body/guard requirements still apply | string | Whether to adjust start/end dates to align with timeframe boundaries and use exclusive end. Defaults to true. When true, dates are aligned to the start of the timeframe period (e.g., start of day) and end is made exclusive (e.g., start of next day). When false, uses exact dates provided. enum: ["true", "false"]. default: "true". | | endpoint_id | Yes | JSON | Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2 | | expand | No; body/guard requirements still apply | JSON | Data and metrics to include in the response. Use 'time_series' for time-bucketed data, metric names for specific metrics in time series, and 'summary' for aggregate statistics. At least one of 'time_series' or 'summary' and at least one metric are required. default: ["time_series", "request_count"]. | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |

input.start

input.start anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.start anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.end

input.end anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.end anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`get_billing_events`

Returns paginated individual billing event records with filters for endpoint and date range. Each record includes the request ID, timestamp, endpoint, output units billed, and a cost breakdown in USD (cost_subtotal, cost_discount, cost_total; cost_estimate_nano_usd carries cost_total in nano USD). Key Features: - Individual billing event records for each API request - Per-request cost breakdown before and after discounts - Flexible date range filtering - Optional endpoint filtering - Cursor-based pagination for efficient large dataset queries - Limited to 10000 records per page for performance - Date range capped at 90 days per request Common Use Cases: - Audit individual billing events - Track request patterns and volumes - Debug specific requests by ID - Monitor billing unit consumption per request See fal.ai docs for more details.

Policy: Read/helper; no explicit mutation approval.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | limit | No; body/guard requirements still apply | integer | Maximum number of items to return. Actual maximum depends on query type and expansion parameters. minimum: 1. | | cursor | No; body/guard requirements still apply | string | Pagination cursor from previous response. Encodes the page number. | | start | No; body/guard requirements still apply | JSON | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. | | end | No; body/guard requirements still apply | JSON | End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time. | | endpoint_id | No; body/guard requirements still apply | JSON | Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2 | | request_id | No; body/guard requirements still apply | JSON | Filter by specific request ID(s). Accepts 1-50 request IDs. Supports comma-separated values: ?request_id=req1,req2 or array syntax: ?request_id=req1&request_id=req2 | | api_key_id | No; body/guard requirements still apply | JSON | Filter by specific API key ID(s). Accepts 1-50 key IDs. Supports comma-separated values: ?api_key_id=key1,key2 or array syntax: ?api_key_id=key1&api_key_id=key2 | | login_username | No; body/guard requirements still apply | JSON | Filter by team member login username(s) (nickname). Accepts 1-50 usernames. Supports comma-separated values: ?login_username=alice,bob or array syntax: ?login_username=alice&login_username=bob | | expand | No; body/guard requirements still apply | JSON | Data to include in the response. Use 'auth_method' for a formatted authentication method label, and 'auth_method_structured' for a machine-readable auth method object (detail, api_key_id, login_username). | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |

input.start

input.start anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.start anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.end

input.end anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.end anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.request_id

input.request_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.request_id anyOf branch 2

input.request_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.api_key_id

input.api_key_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.api_key_id anyOf branch 2

input.api_key_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.login_username

input.login_username anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.login_username anyOf branch 2

input.login_username.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`delete_request_payloads`

Deletes the IO payloads and associated CDN output files for a specific request. Important: - Only output CDN files are deleted (input files may be used by other requests) - This action is irreversible - Requires authentication with an admin API key What gets deleted: - Request input/output payload data - CDN-hosted output files (images, videos, etc.) What is NOT deleted: - Input CDN files (may be referenced by other requests) Response: - Returns deletion status for each CDN file - Each result includes the file link and any error that occurred Idempotency: - Optional Idempotency-Key header prevents duplicate deletions on retries - Responses cached for 10 minutes per unique key See fal.ai docs for more details about request payloads.

Policy: Confirmed operation; read-only hides and directly refuses it.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | request_id | Yes | string | Unique identifier for the request (UUID format) format: "uuid". | | Idempotency_Key | No; body/guard requirements still apply | string | Optional idempotency key for safe request retries | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |

`list_requests_by_endpoint`

Lists requests for one or more endpoints (same endpoint_id style as usage/explore: comma-separated or repeated query params, up to 50 IDs). Authentication: Requires API key (user or enterprise). Filters: - Time range via start / end. If start is omitted, defaults to the last 24 hours : unless request_id is provided, in which case the default start bound is widened to 90 days. - Status (success, error, user_error) - Request ID - Pagination via cursor/limit (limit defaults to 50, max 100) Sorting: - By end time (default) or duration Expansions: - Include payloads by adding expand=payloads

Policy: Read/helper; no explicit mutation approval.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | limit | No; body/guard requirements still apply | integer | Number of items to return per page (max 100) minimum: 1. maximum: 100. default: 50. | | cursor | No; body/guard requirements still apply | string | Pagination cursor encoding the page number | | endpoint_id | Yes | JSON | Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2 | | start | No; body/guard requirements still apply | JSON | Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago. | | end | No; body/guard requirements still apply | JSON | End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time. | | status | No; body/guard requirements still apply | string | Filter by request status enum: ["success", "error", "user_error"]. | | request_id | No; body/guard requirements still apply | string | Filter by specific request ID format: "uuid". | | expand | No; body/guard requirements still apply | JSON | Fields to expand in the response. Use payloads to include input and output payloads. | | sort_by | No; body/guard requirements still apply | string | Sort results by end time or duration enum: ["ended_at", "duration"]. default: "ended_at". | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

input.start

input.start anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.start anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.end

input.end anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.end anyOf branch 2

Native JSON value; inspect the full schema for validation.

input.expand

input.expand anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.expand anyOf branch 2

input.expand.anyOf2[]

Native JSON value; inspect the full schema for validation.

`search_requests`

Search, filter, and browse your request history. Supports three modes: 1. Semantic Search (query, image_url, or video_url parameter): Find visually or conceptually similar results using AI embeddings. Provide a text query for text-to-image search, an image URL for image-to-image similarity search, or a video URL for video-to-image similarity search. 2. Filtered Browse (no query, image_url, or video_url): Browse request history with hard filters. Returns results ordered by creation date (newest first). 3. Semantic + Filters (search params AND filter params): Combine semantic search with hard filters. Filters narrow the candidate set before ranking by similarity. Filter Options: - endpoint_id: Filter by one or more fal endpoints (comma-separated or repeated, up to 50 IDs) - exclude_api_requests / only_api_requests: Filter by request source Examples: - Semantic text search: ?query=sunset+landscape - Image similarity: ?image_url=https://...&min_similarity=0.5 - Filtered search: ?query=portrait&endpoint_id=fal-ai/flux/dev - Browse across multiple endpoints: ?endpoint_id=fal-ai/flux/dev,fal-ai/flux/schnell

Policy: Read/helper; no explicit mutation approval.

input.endpoint_id

input.endpoint_id anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.endpoint_id anyOf branch 2

input.endpoint_id.anyOf2[]

Native JSON value; inspect the full schema for validation.

`list_workflows`

List workflows for the authenticated user with optional search and filtering. Features: - Paginated results with cursor-based pagination - Search by workflow name or title - Filter by model endpoints used in the workflow Authentication: Required. Returns only workflows owned by the authenticated user. Common Use Cases: - Display user's workflow library - Search for specific workflows - Find workflows using particular models

Policy: Read/helper; no explicit mutation approval.

input.used_endpoint_ids

input.used_endpoint_ids anyOf branch 1

Native JSON value; inspect the full schema for validation.

input.used_endpoint_ids anyOf branch 2

input.used_endpoint_ids.anyOf2[]

Native JSON value; inspect the full schema for validation.

`create_workflow`

Create a new workflow owned by the authenticated user. Authentication: Required. Common Use Cases: - Save a newly built workflow - Programmatically provision workflows Note: Workflow names must be unique within your namespace. Creating a workflow with a name you already use returns a 400 validation error.

Policy: Confirmed operation; read-only hides and directly refuses it.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | name | No; body/guard requirements still apply | string | Unique workflow name/slug within the user's namespace maxLength: 128. pattern: "^[a-zA-Z0-9_-]+$". | | title | No; body/guard requirements still apply | string | Human-readable workflow title minLength: 1. maxLength: 256. | | contents | No; body/guard requirements still apply | object | The workflow definition/configuration object | | is_public | No; body/guard requirements still apply | boolean | Whether the workflow is publicly visible default: false. | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: 1. |

input.contents

| Argument | Required | Type | Details | | --- | --- | --- | --- | | name | Yes | string | Internal name of the workflow definition | | version | Yes | string | Workflow definition format version | | nodes | Yes | object | Workflow nodes keyed by node id | | output | Yes | object | Output field mappings keyed by output name | | schema | Yes | object | Input/output schema for the workflow | | metadata | No; body/guard requirements still apply | object | Optional workflow metadata |

input.contents.nodes

input.contents.nodes.{key}

input.contents.nodes.{key}.{key}

Native JSON value; inspect the full schema for validation.

input.contents.output

input.contents.output.{key}

Native JSON value; inspect the full schema for validation.

input.contents.schema

| Argument | Required | Type | Details | | --- | --- | --- | --- | | input | Yes | object | Input fields schema | | output | Yes | object | Output fields schema |

input.contents.schema.input

input.contents.schema.input.{key}

Native JSON value; inspect the full schema for validation.

input.contents.schema.output

input.contents.schema.output.{key}

Native JSON value; inspect the full schema for validation.

input.contents.metadata

input.contents.metadata.{key}

Native JSON value; inspect the full schema for validation.

input.payload

| Argument | Required | Type | Details | | --- | --- | --- | --- | | name | Yes | string | Unique workflow name/slug within the user's namespace maxLength: 128. pattern: "^[a-zA-Z0-9_-]+$". | | title | Yes | string | Human-readable workflow title minLength: 1. maxLength: 256. | | contents | Yes | object | The workflow definition/configuration object | | is_public | No; body/guard requirements still apply | boolean | Whether the workflow is publicly visible default: false. |

input.payload.contents

input.payload.contents.nodes

input.payload.contents.nodes.{key}

input.payload.contents.nodes.{key}.{key}

Native JSON value; inspect the full schema for validation.

input.payload.contents.output

input.payload.contents.output.{key}

Native JSON value; inspect the full schema for validation.

input.payload.contents.schema

| Argument | Required | Type | Details | | --- | --- | --- | --- | | input | Yes | object | Input fields schema | | output | Yes | object | Output fields schema |

input.payload.contents.schema.input

input.payload.contents.schema.input.{key}

Native JSON value; inspect the full schema for validation.

input.payload.contents.schema.output

input.payload.contents.schema.output.{key}

Native JSON value; inspect the full schema for validation.

input.payload.contents.metadata

input.payload.contents.metadata.{key}

Native JSON value; inspect the full schema for validation.

`get_workflow`

Get detailed information about a specific workflow, including its full contents/definition. Authentication: Required. Common Use Cases: - Load a workflow for editing - View workflow configuration - Export workflow definition

Policy: Read/helper; no explicit mutation approval.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | username | Yes | string | The username of the workflow owner maxLength: 128. pattern: "^[a-zA-Z0-9_-]+$". | | workflow_name | Yes | string | The workflow name/slug maxLength: 128. pattern: "^[a-zA-Z0-9_-]+$". | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |

`list_assets`

Browse and semantically search fal Assets across all media, uploads, favorites, collections, tags, and character references.

Policy: Read/helper; no explicit mutation approval.

input.media_type

input.media_type[]

Asset media type

input.source

input.source[]

Indexed asset source

input.character_identifier

input.character_identifier[]

Native JSON value; inspect the full schema for validation.

input.tag_id

input.tag_id[]

Native JSON value; inspect the full schema for validation.

`list_asset_collections`

List asset collections for the authenticated user's fal Assets library.

Policy: Read/helper; no explicit mutation approval.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | limit | No; body/guard requirements still apply | integer | Maximum number of collections to return minimum: 1. maximum: 100. default: 50. | | offset | No; body/guard requirements still apply | ['integer', 'null'] | Number of collections to skip minimum: 0. default: 0. | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |

`create_asset_collection`

Create asset collection for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | Idempotency_Key | No; body/guard requirements still apply | string | Optional idempotency key for safe request retries | | name | No; body/guard requirements still apply | string | Collection display name minLength: 1. maxLength: 255. | | description | No; body/guard requirements still apply | ['string', 'null'] | Optional collection description | | icon | No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon | | color | No; body/guard requirements still apply | ['string', 'null'] | Optional collection color | | cover_image_url | No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: "uri". | | parent_collection_id | No; body/guard requirements still apply | ['string', 'null'] | Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection. minLength: 1. | | filters | No; body/guard requirements still apply | JSON | Assets filter DSL | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: 1. |

input.payload

| Argument | Required | Type | Details | | --- | --- | --- | --- | | name | Yes | string | Collection display name minLength: 1. maxLength: 255. | | description | No; body/guard requirements still apply | ['string', 'null'] | Optional collection description | | icon | No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon | | color | No; body/guard requirements still apply | ['string', 'null'] | Optional collection color | | cover_image_url | No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: "uri". | | parent_collection_id | No; body/guard requirements still apply | ['string', 'null'] | Optional parent collection ID to nest this collection under (manual collections only). Omit or null to create a top-level collection. minLength: 1. | | filters | No; body/guard requirements still apply | JSON | Assets filter DSL |

`get_asset_collection`

Get asset collection for the authenticated user's fal Assets library.

Policy: Read/helper; no explicit mutation approval.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | collection_id | Yes | string | Collection ID minLength: 1. | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. |

`update_asset_collection`

Update asset collection for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | collection_id | Yes | string | Collection ID minLength: 1. | | Idempotency_Key | No; body/guard requirements still apply | string | Optional idempotency key for safe request retries | | name | No; body/guard requirements still apply | string | Collection display name minLength: 1. maxLength: 255. | | description | No; body/guard requirements still apply | ['string', 'null'] | Optional collection description | | icon | No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon | | color | No; body/guard requirements still apply | ['string', 'null'] | Optional collection color | | cover_image_url | No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: "uri". | | filters | No; body/guard requirements still apply | JSON | Assets filter DSL | | account | No; body/guard requirements still apply | string | Exact private account key profile label, not an authenticated provider owner ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs. minLength: 1. |

input.payload

| Argument | Required | Type | Details | | --- | --- | --- | --- | | name | No; body/guard requirements still apply | string | Collection display name minLength: 1. maxLength: 255. | | description | No; body/guard requirements still apply | ['string', 'null'] | Optional collection description | | icon | No; body/guard requirements still apply | ['string', 'null'] | Optional collection icon | | color | No; body/guard requirements still apply | ['string', 'null'] | Optional collection color | | cover_image_url | No; body/guard requirements still apply | ['string', 'null'] | Optional fal-hosted cover image URL for the collection format: "uri". | | filters | No; body/guard requirements still apply | JSON | Assets filter DSL |

`delete_asset_collection`

Delete asset collection for the authenticated user's fal Assets library.

Policy: Confirmed operation; read-only hides and directly refuses it.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

fal.ai MCP Server & CLI

Two ways to use it

Command line

MCP server, for your AI app

Which one

Features

Contents

1. What you can ask it

2. Quick install

3. Set up fal.ai access

Private account access

Official account connections

Costs and permissions

Data and file controls

Rotation and revocation

4. Connect your client

5. Check it works

6. Output, flags and exit codes

7. MCP or CLI and token cost

8. Every tool and argument

search_models

get_pricing

estimate_pricing

get_usage

get_analytics

get_billing_events

delete_request_payloads

list_requests_by_endpoint

search_requests

list_workflows

create_workflow

get_workflow

list_assets

list_asset_collections

create_asset_collection

get_asset_collection

update_asset_collection

delete_asset_collection

`search_models`

`get_pricing`

`estimate_pricing`

`get_usage`

`get_analytics`

`get_billing_events`

`delete_request_payloads`

`list_requests_by_endpoint`

`search_requests`

`list_workflows`

`create_workflow`

`get_workflow`

`list_assets`

`list_asset_collections`

`create_asset_collection`

`get_asset_collection`

`update_asset_collection`

`delete_asset_collection`