Run MCP

Connect AI coding assistants to fal’s 1,000+ models via the Model Context Protocol

Use fal’s MCP server to search models, check schemas and pricing, run inference, upload files, and search documentation from your AI assistant.

The hosted endpoint is https://mcp.fal.ai/mcp. Connect with a client that supports Streamable HTTP, such as Claude Code, Cursor, or Windsurf. The API-key examples below use your fal API key. The plugin and OAuth connectors use your fal sign-in.

For account operations and serverless debugging, connect the Platform MCP. You can use both servers together.

For the API-key setup below, create a fal API key. In ChatGPT or Codex, install the fal plugin. See the plugin setup guide to connect your fal account.

Setup

ChatGPT / Codex

1. Open the fal plugin listing.
2. Install the plugin.
3. Connect your fal account when prompted.
4. Start a new chat and ask your assistant to use fal.

See the plugin guide for examples and account selection.

Claude Code

This setup is for Claude Code, the terminal/IDE client, using a fal API key. OAuth connectors use a separate sign-in flow.

Replace YOUR_FAL_KEY with your fal API key. Run this command in your terminal:

claude mcp add --transport http fal-ai \
  https://mcp.fal.ai/mcp \
  --header "Authorization: Bearer YOUR_FAL_KEY"

In Claude Code, run /mcp to check that fal-ai is connected. See Claude Code’s MCP guide for connection troubleshooting.

Cursor

1. Open the configuration file

   Open or create ~/.cursor/mcp.json for access across your projects.

2. Add the fal server

   Add this server to mcpServers. Replace YOUR_FAL_KEY with your fal API key:

   {
     "mcpServers": {
       "fal-ai": {
         "url": "https://mcp.fal.ai/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_FAL_KEY"
         }
       }
     }
   }
   
3. Check the connection

   Save the file. Check that fal-ai is available in Cursor’s MCP settings.

See Cursor’s MCP guide for configuration details.

Windsurf

Open ~/.codeium/windsurf/mcp_config.json. Add this server to mcpServers. Replace YOUR_FAL_KEY with your fal API key:

{
  "mcpServers": {
    "fal-ai": {
      "serverUrl": "https://mcp.fal.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_FAL_KEY"
      }
    }
  }
}

Save the file and enable fal-ai in Cascade’s MCP settings. See the MCP configuration guide for details.

Other MCP Clients

The fal MCP server uses the Streamable HTTP transport at:

https://mcp.fal.ai/mcp

Authentication is via the Authorization header:

Authorization: Bearer YOUR_FAL_KEY

Use a client that supports Streamable HTTP and custom authorization headers. Refer to your client’s documentation for the exact configuration format.

Check the connection

Ask your assistant:

Use fal to search for image generation models. Do not run a model.

A successful connection returns model search results. If authentication fails, check the configured API key or complete the connector’s fal sign-in.

Choose your OAuth account

OAuth connections use your personal fal account until you choose another. In Account settings, open the desired account’s row menu and choose Use for MCP.

The change applies immediately to future operations across all your OAuth MCP connections, including the fal plugin in ChatGPT and Codex. No reconnect or plugin reinstall is needed. This preference is separate from the website’s account switcher.

Existing jobs stay on the account that started them. MCP responses show which account was used. If access to the selected account fails, operations stop instead of using your personal credits. API-key connections keep using the account associated with their key.

---

Available Tools

The server provides 11 tools for discovery, execution, and uploads.

Discovery

Tool	What it does
search_models	Search fal’s catalog of 1,000+ models by keyword or category
get_model_schema	Get the full input/output parameters for any model
get_pricing	Check the cost of running a model before you use it
search_docs	Search the fal documentation for guides, examples, and API references

Execution

Tool	What it does
run_model	Run a model with a bounded wait. Return the result or request ID and URLs to continue polling
submit_job	Submit a long-running job and return immediately with a request ID
check_job	Check the status of a submitted job
get_job_result	Fetch the result of a completed job
cancel_job	Cancel a queued or running job

Utility

Tool	What it does
upload_file	Upload a public file URL or base64 data to fal’s CDN
recommend_model	Describe what you want to build and get model recommendations

---

Examples

Generate an image

“Generate a photorealistic image of a mountain lake at golden hour using fal”

The assistant will:

1. Use recommend_model to find a model, or search_models if you named one
2. Use get_model_schema to check the parameters for the chosen model
3. Use run_model to generate the image
4. Return the image URL

Generate a video from an image

“Take this image and turn it into a 5-second cinematic video”

The assistant will:

1. Use upload_file to upload your image to fal’s CDN
2. Use recommend_model to find an image-to-video model
3. Use submit_job (since video generation takes longer)
4. Use check_job to poll for completion, then get_job_result to fetch the output

Check pricing before running

“How much does it cost to generate a video with Kling 3.0?”

The assistant will call get_pricing with fal-ai/kling-video/v3/pro/image-to-video and return the per-run cost.

Find the right model

“What’s the best model for removing backgrounds from product photos?”

The assistant will call recommend_model with your task description and return a ranked list of models with tips on how to use them.

Search the docs

“How do I set up webhooks with fal?”

The assistant will call search_docs and return relevant guides and code examples from the fal documentation.

---

How It Works

fal hosts the MCP server. It authenticates each request with your API key or OAuth token.

1. Your AI assistant sends a request to mcp.fal.ai/mcp with your API key or OAuth token
2. The server calls the fal Platform API on your behalf
3. Results are returned to your assistant, which formats them for you

API keys and OAuth tokens are sent per request in the Authorization header. The server uses the connected account’s permissions to call fal. It caches some API responses and can record usage metadata, such as tool names, model IDs, duration, and outcome. Credentials, prompts, media, and input/output payloads are not sent to its usage analytics.

The MCP server uses the same Model APIs you would call directly with the fal client SDK. The tools cover model discovery, generation, queue management, and uploads.

---

Tool Reference

search_models

Search fal’s model catalog by keyword, category, or both.

Parameters:

Parameter	Type	Description
query	string (optional)	Free-text search, e.g. "flux", "video generation", "upscale"
category	string (optional)	Filter by category: text-to-image, image-to-video, text-to-video, text-to-speech, image-to-3d, image-editing, llm, and more
limit	number (optional)	Max results to return (default 20, max 100)
cursor	string (optional)	Pagination cursor. Pass the next_cursor value from a previous search_models response to fetch the next page.

Example response:

{
  "models": [
    {
      "endpoint_id": "fal-ai/flux/dev",
      "name": "FLUX.1 [dev]",
      "category": "text-to-image",
      "description": "State-of-the-art text-to-image model"
    }
  ],
  "total_shown": 1,
  "has_more": true,
  "next_cursor": "eyJvZmZzZXQiOjIwfQ"
}

---

get_model_schema

Get the full input/output schema for a specific model. Use this before run_model to understand what parameters are accepted.

Parameters:

Parameter	Type	Description
endpoint_id	string	The model ID, e.g. "fal-ai/flux/dev"

---

run_model

Run a fal model through the queue. The server waits up to 45 seconds by default. It returns completed with the result or processing with a request ID and URLs to check the job.

Parameters:

Parameter	Type	Description
endpoint_id	string	The model ID, e.g. "fal-ai/flux/dev"
input	object	Model parameters as JSON. Use get_model_schema to see accepted fields.
expiration_seconds	number (optional)	Positive CDN lifetime in seconds for generated media. Omit to use the account default.
store_payload	boolean (optional)	Set to false to disable request payload storage in fal and omit recipe.input from the response. See Response recipe.

Example:

{
  "endpoint_id": "fal-ai/flux/dev",
  "input": {
    "prompt": "a photorealistic mountain landscape at sunset",
    "image_size": "landscape_16_9"
  }
}

For long-running models (video, 3D, training), use submit_job → check_job → get_job_result from the start.

If run_model returns processing, keep its request_id and pass its status_url to check_job. Respect poll_after_seconds when present. Once check_job returns status: "COMPLETED", call get_job_result with the returned response_url. Do not resubmit to check progress: another run_model or submit_job call creates a new billable job.

---

submit_job

Submit a job without waiting for the result. Returns immediately with a request_id you can use with check_job.

Parameters:

Parameter	Type	Description
endpoint_id	string	The model ID
input	object	Model parameters as JSON
expiration_seconds	number (optional)	Positive CDN lifetime in seconds for generated media. Omit to use the account default.
store_payload	boolean (optional)	Set to false to disable request payload storage in fal and omit recipe.input from the response. See Response recipe.

---

Response recipe

Both run_model and submit_job return a recipe object with the endpoint ID and submitted inputs. These response excerpts show how store_payload changes that object.

Default

{
  "recipe": {
    "endpoint_id": "fal-ai/flux/dev",
    "input": { "prompt": "a mountain lake" }
  }
}

With store_payload: false, recipe.input is absent and recipe.input_omitted is true.

---

check_job

Check a job’s status. Use get_job_result to fetch the output or cancel_job to cancel it.

Parameters:

Parameter	Type	Description
endpoint_id	string	The model ID
request_id	string	The request ID from run_model or submit_job
status_url	string (optional)	Status URL returned by submit_job, or by run_model when it returns processing. Used instead of deriving it.

---

get_job_result

Fetch the result of a completed job.

Parameters:

Parameter	Type	Description
endpoint_id	string	The model ID
request_id	string	The request ID from run_model or submit_job
response_url	string (optional)	Response URL returned by submit_job, or by run_model when it returns processing. Used instead of deriving it.

---

cancel_job

Cancel a queued or running job.

Parameters:

Parameter	Type	Description
endpoint_id	string	The model ID
request_id	string	The request ID from run_model or submit_job
cancel_url	string (optional)	Cancel URL returned by submit_job, or by run_model when it returns processing. Used instead of deriving it.

---

upload_file

Upload a file to fal’s CDN for use as model input. Provide exactly one source, either url or data.

Parameters:

Parameter	Type	Description
url	string (optional)	Public HTTP(S) file URL
data	string (optional)	Complete base64-encoded file contents
file_name	string (optional)	Filename including extension. Include it with data to identify the content type.

Use base64 for small local files (under 1 MB). For larger inputs, provide a public file URL. Sending a local path to the hosted server will fail.

Returns a cdn_url that you can pass to any model parameter that accepts a URL (e.g. image_url, audio_url).

---

get_pricing

Get the cost of running a model.

Parameters:

Parameter	Type	Description
endpoint_id	string	The model ID to check pricing for

---

recommend_model

Describe what you want to create and get model recommendations ranked by popularity.

Parameters:

Parameter	Type	Description
task	string	What you want to do, e.g. "generate a photorealistic portrait", "create a 10s cinematic video", "remove background from an image"

---

search_docs

Search the fal documentation for guides, API references, and code examples.

Parameters:

Parameter	Type	Description
query	string	What you’re looking for, e.g. "how to upload a file", "queue API", "LoRA training"

---

FAQ

My credits are on a team account

In Account settings, open your team’s row menu and choose Use for MCP. Switching accounts on the website alone does not change your OAuth MCP account. For API-key connections, use a key belonging to the team.

What models can I use?

Models in the fal catalog include image, video, audio, speech, 3D, and language models. Use search_models or recommend_model to find what you need.

Is my API key stored?

No. Your key is sent per request in the Authorization header. It is not persisted or logged as a credential. The server can record usage metadata. See How It Works.

Does it cost extra?

No. The MCP server is free. You only pay for the fal model runs you trigger, at the same pricing as direct API calls.

What about rate limits?

The MCP server respects the same concurrency limits as direct API calls. There are no additional rate limits on the MCP endpoint itself.