Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the fal MCP server

Vendor MCP
Open markdown

The fal MCP connector routes your AI agent's tool calls to fal's own MCP server through Scalekit. Each user signs in to fal once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 42 tools.

Tools
42
What they doRead · write · destructive
29 · 10 · 329 read10 write3 destructive
Users sign in with
OAuth app
Your own fal MCP server app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the fal MCP connection

    In AgentKit > Connections, create a fal MCP connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    fal MCP server connections use your own OAuth app. Register one with fal MCP server and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the fal MCP connection.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'falmcp'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize fal MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'falmcp_browse_models',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • falmcp_browse_modelsBrowse active model endpoints by canonical category with Explore's Trending or Recently added order.Read-only

    Browse fal.ai Models

    Browse active model endpoints by canonical category with Explore's Trending or Recently added order. Use search_models for keywords such as music, upscaling, background removal or specific model names; use recommend_model to choose a model for a task. Category image-to-image covers image edits and transforms; aliases such as image-editing, tts or i2v are mapped to canonical categories. Music has no text-to-music category: search for music, rather than broadening to all text-to-audio models. Sorting is performed by the server before pagination, never on one local page. Trending is shared discovery order, not a quality, speed or authored recommendation rank. Entries keep that order; fal's published picks are tagged recommended, and a caveat marks entries that are off-task unless asked for (superseded by a listed newer version, routed as another task, trainer, LoRA/style/preset variant, streaming, not callable). Recent requires a supporting catalog API and explicit ordering acknowledgement. Entries tagged callable: false are catalog listings that can't run through MCP: a realtime session app is playground-only at its playground_url; other such listings carry only a model_page_url and no playground.

    Inputs

    categorystring
    Canonical category such as image-to-image, text-to-image, image-to-video, video-to-video, text-to-audio or training. Omit to browse all active endpoints.
    cursorstring
    next_cursor from the previous page. Keep category, sort and limit unchanged. Catalog cursors are page positions, not snapshots.
    limitinteger
    Page size, default 20. Keep it unchanged when following a cursor.
    sortstring
    trending (default) follows Explore's shared browse order; recent is Recently added, by publication date with creation date as fallback.one of trendingrecent
    user_intentstring
    The user's request that prompted this tool call, copied verbatim. Preserve their wording and constraints; do not summarize, infer missing details, or substitute your generation prompt. Omit when the original request text is unavailable. Agent-reported context, not verified conversation history.
  • falmcp_check_account_statusCheck the connected fal account when the user asks about it, after a billing block once the user says they added credits, or after changing accounts.Read-only

    Check fal Account Readiness

    Check the connected fal account when the user asks about it, after a billing block once the user says they added credits, or after changing accounts. Not needed before a generation or upload: those report a billing block themselves, with recovery steps. Returns ready, blocked, or unknown with account identity when available and recovery instructions. A billing block lists its capabilities: model search, schemas and pricing still work, uploads and generations don't. This is read-only: it never purchases credits, changes accounts, uploads files, submits or resumes jobs. Ready means no account-level lock was reported, not that a particular job is affordable or permitted. Unknown does not mean insufficient balance. Explain a block once and wait for the user; do not poll this tool or automatically retry paid work. Keep existing request IDs and resume their original jobs rather than submitting duplicates.

    Inputs

    request_idstring
    For an existing job, check its original account using the returned request_id. Omit for a new task.
    status_urlstring
    Saved status_url for that request_id, including its account recovery receipt when present. Only supply with request_id.
    user_intentstring
    The user's request that prompted this tool call, copied verbatim. Preserve their wording and constraints; do not summarize, infer missing details, or substitute your generation prompt. Omit when the original request text is unavailable. Agent-reported context, not verified conversation history.
  • falmcp_estimate_costEstimate a request's cost from the connected account's current model rate and explicit billing units, when the user asks what it will cost or sets a budget; it isn't a required step before running a model.Read-only

    Estimate Model Cost

    Estimate a request's cost from the connected account's current model rate and explicit billing units, when the user asks what it will cost or sets a budget; it isn't a required step before running a model. Read-only and advisory: never submits, uploads, checks affordability, or enforces a cost cap. Pass the actual model input to use explicit num_images, duration, duration_seconds, seconds_total or music_length_ms where the billing unit matches. For other units pass unit_quantity with the exact unit returned by get_pricing. Never infer compute time, model defaults, media duration, pixel rounding, or unit conversions. Configuration-specific pricing rules and minimum charges are not exposed by the pricing API, so totals are estimates. Unknown is not free; do not treat an estimate as a quote, final charge, or approval. Rates may be cached for up to 5 minutes.

    Inputs

    endpoint_idstringrequired
    One exact fal model endpoint ID; use get_pricing for batch model comparisons
    inputobject
    Actual model input JSON, including explicit count/duration when known. No files are fetched and omitted defaults are not guessed.
    unit_quantityobject
    Explicit expected billable units. Both quantity and the exact billing unit are required; overrides quantity inferred from input.
    user_intentstring
    The user's request that prompted this tool call, copied verbatim. Preserve their wording and constraints; do not summarize, infer missing details, or substitute your generation prompt. Omit when the original request text is unavailable. Agent-reported context, not verified conversation history.
  • falmcp_get_generation_defaultsRead safely scoped personal/account generation preferences and preferred models.Read-only

    Get Generation Defaults

    Read safely scoped personal/account generation preferences and preferred models. Explicit current requirements win; variations keep the actual source recipe ahead of saved preferences. No defaults are written or inferred. Team credentials must not inherit another member's private preferences; inspect identity and scope.

    Inputs

    user_intentstring
    The user's request that prompted this tool call, copied verbatim. Preserve their wording and constraints; do not summarize, infer missing details, or substitute your generation prompt. Omit when the original request text is unavailable. Agent-reported context, not verified conversation history.
  • falmcp_get_job_recipeRecover the exact retained input and output for one existing model request from public request history.Read-only

    Get original job recipe

    Recover the exact retained input and output for one existing model request from public request history. Pass the original endpoint_id and request_id; preserve the row's account_receipt from search_request_history or the original job's response_url so OAuth uses the original account after later selection changes. Receipts are bound to the authenticated user, connection issuer and request ID; conflicting receipts or existing job bindings are rejected. Default lookup covers 90 days; start/end can select another indexed interval. A reusable recipe is returned only for an actually retained object input. Missing/expired/omitted payloads or absent history remain unknown; no defaults, prompts, references, or model settings are reconstructed. Requires models:requests:read and permission to view the original account's requests. Does not resubmit, save media, or change the account for new work.

    Inputs

    endpoint_idstringrequired
    No description.
    request_idstringrequired
    No description.
    account_receiptstring
    Copy the exact account_receipt returned for this request ID by search_request_history. Used only for original-account authorization, never sent to the history API.
    endstring
    No description.
    response_urlstring
    Original job response_url, including its account recovery receipt if present. Used only for account authorization, not as a history fetch target.
    startstring
    No description.
    user_intentstring
    The user's request that prompted this tool call, copied verbatim. Preserve their wording and constraints; do not summarize, infer missing details, or substitute your generation prompt. Omit when the original request text is unavailable. Agent-reported context, not verified conversation history.
  • falmcp_get_model_schemaGet the input/output schema for a specific fal.ai model.Read-only

    Get Model Schema

    Get the input/output schema for a specific fal.ai model. Returns every parameter the model accepts as input_params plus one inlined input_schema, what it returns as output_fields and output_schema, and the exact OpenAPI forms (exact_input_schema, exact_output_schema, components). Pass detail: 'compact' to omit the exact OpenAPI forms and the output schema. Includes published guidance and v3 evidence in model_knowledge when available. Report latency p50/p90 in milliseconds with the measurement window: successful execution, mixed workloads, excludes queue/startup, not runtime guarantees. Null means unknown. Not needed before running a model recommend_model selected: its next_call carries the complete input contract, and run_model/submit_job validate input against the live schema before any charge. Use this for a model you chose yourself or the user named. An unknown ID returns status not_found with exact catalog suggestions. To compare several models, pass endpoint_ids: up to 10 compact schemas from one catalog read, instead of one call per model.

    Inputs

    endpoint_idstringrequired
    The model endpoint ID (e.g. 'fal-ai/flux/dev', 'fal-ai/wan-t2v')
    detailstring
    full (default): every schema form, as before. compact: one inlined input schema and parameter summaries, without the exact OpenAPI schemas, output schema and components.one of compactfull
    endpoint_idsarray
    Up to 9 more endpoint IDs to compare with endpoint_id. Returns compact schemas for all of them from one catalog read; detail is ignored.
    user_intentstring
    The user's request that prompted this tool call, copied verbatim. Preserve their wording and constraints; do not summarize, infer missing details, or substitute your generation prompt. Omit when the original request text is unavailable. Agent-reported context, not verified conversation history.
  • falmcp_get_pricingGet pricing information for fal.ai models.Read-only

    Get Model Pricing

    Get pricing information for fal.ai models. Returns cost per run or per second. Use this when the user asks what a model costs, sets a budget, or wants models compared by price; recommend_model's next_call.price usually has the selected model's rate already. It isn't a required step before running a model. When comparing models, batch up to 50 comma-separated endpoint IDs in one call to avoid the account's pricing rate limit. Pricing estimates may be cached for up to 5 minutes; reuse a recent lookup instead of checking it for every job. An unknown single ID returns status not_found with exact catalog suggestions.

    Inputs

    endpoint_idstring
    One model endpoint ID, or up to 50 comma-separated endpoint IDs to compare in one request
    endpoint_idsarray
    Endpoint IDs to compare, as an array instead of a comma-separated endpoint_id. Up to 50 in total.
    user_intentstring
    The user's request that prompted this tool call, copied verbatim. Preserve their wording and constraints; do not summarize, infer missing details, or substitute your generation prompt. Omit when the original request text is unavailable. Agent-reported context, not verified conversation history.
  • falmcp_get_submissionRead the shared journal for a client-generated submission_key after a lost tool response.Read-only

    Recover a submission by its original key

    Read the shared journal for a client-generated submission_key after a lost tool response. Returns original job handles, a definite rejection, not_found, or submission_unknown. Never submits, polls, retries, or changes the payer. Unknown/not_found do not authorize a new paid generation.

    Inputs

    submission_keystringrequired
    Create a random key once per intended generation and preserve it across retries. The same key and exact request recover the original job. Changed inputs, payer or batch index conflict. Use a new key only for a deliberate new generation. Requires the shared submission journal; unavailable storage blocks keyed submissions before charge.
    user_intentstring
    The user's request that prompted this tool call, copied verbatim. Preserve their wording and constraints; do not summarize, infer missing details, or substitute your generation prompt. Omit when the original request text is unavailable. Agent-reported context, not verified conversation history.