How do I use @monsoft/mcp-fal-ai?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@monsoft/mcp-fal-ai generate an image of a sunset over mountains using fal.ai" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

@monsoft/mcp-fal-ai

by Forge-Systems-Hub

Overview Schema Related Servers Score Discussions

TypeScript

Remote

MCP fal.ai Integration

npm version License: MIT

An MCP (Model Context Protocol) server that integrates with fal.ai to provide seamless access to AI models for image generation, text processing, audio synthesis, and more. Use this package to connect AI agents like Cursor, Claude Desktop, ChatGPT, and other MCP-compatible tools to fal.ai's powerful AI model catalog.

Features

✨ 8 Tools for model discovery, execution, and job management
🔗 4 Resources for configuration and documentation
📝 1 Prompt for image generation assistance
🚀 Dual Transport support (stdio and SSE)
🔒 Type-safe with full TypeScript support
🎯 Zero dependencies on fal.ai SDK (pure HTTP client)

Related MCP server: fal-mcp

Installation

NPM Package

npm install -g @monsoft/mcp-fal-ai

Or install locally in your project:

npm install @monsoft/mcp-fal-ai

From Source

git clone https://github.com/Monsoft-Solutions/model-context-protocols.git
cd model-context-protocols/packages/mcp-fal-ai
npm install
npm run build

Getting Your fal.ai API Key

Before using this MCP server, you need a fal.ai API key:

Visit fal.ai dashboard
Sign up or log in with your account
Navigate to API Keys section
Create a new API key
Copy the key for configuration (next section)

MCP Setup Instructions

Configure this MCP server in your AI agent by following the instructions for your specific tool.

🎯 Cursor IDE

Open Cursor Settings (Cmd/Ctrl + ,)
Navigate to Features → Model Context Protocol
Click Add MCP Server or edit your MCP configuration file
Add the following configuration:

Using global npm installation:

{
    "mcpServers": {
        "fal-ai": {
            "command": "mcp-fal-ai",
            "env": {
                "FAL_API_KEY": "your-fal-api-key-here"
            }
        }
    }
}

Using npx:

{
    "mcpServers": {
        "fal-ai": {
            "command": "npx",
            "args": ["-y", "@monsoft/mcp-fal-ai"],
            "env": {
                "FAL_API_KEY": "your-fal-api-key-here"
            }
        }
    }
}

Save and restart Cursor
The fal.ai tools should now be available in your agent context

🤖 Claude Desktop

Locate your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Add or update the MCP server configuration:

{
    "mcpServers": {
        "fal-ai": {
            "command": "npx",
            "args": ["-y", "@monsoft/mcp-fal-ai"],
            "env": {
                "FAL_API_KEY": "your-fal-api-key-here"
            }
        }
    }
}

Save the file and restart Claude Desktop
Look for the 🔌 icon in Claude to verify the MCP server is connected

💬 ChatGPT (OpenAI Desktop or Custom Integration)

For ChatGPT with MCP support (if available):

Access your MCP configuration settings
Add the server using npx:

{
    "mcpServers": {
        "fal-ai": {
            "command": "npx",
            "args": ["-y", "@monsoft/mcp-fal-ai"],
            "env": {
                "FAL_API_KEY": "your-fal-api-key-here"
            }
        }
    }
}

🛠️ Generic MCP Client

For any MCP-compatible client:

Using stdio transport:

FAL_API_KEY=your-api-key npx @monsoft/mcp-fal-ai

Using SSE transport:

FAL_API_KEY=your-api-key npx @monsoft/mcp-fal-ai --run-sse --port 3001

Configuration options:

{
    "command": "npx",
    "args": ["-y", "@monsoft/mcp-fal-ai"],
    "env": {
        "FAL_API_KEY": "your-fal-api-key-here",
        "RUN_SSE": "false",
        "PORT": "3001"
    }
}

🔧 CLI Flags

You can also pass configuration via command-line flags:

--fal-api-key or -k: Your fal.ai API key
--run-sse or -s: Enable SSE transport (default: false)
--port or -p: Port for SSE server (default: 3001)

Example:

npx @monsoft/mcp-fal-ai --fal-api-key YOUR_KEY --run-sse --port 3001

Quick Start Examples

Once configured in your AI agent, you can use the fal.ai tools directly in your conversations:

Example 1: Generate an Image

User: Use fal.ai to generate an image of a sunset over mountains

Agent: I'll help you generate that image using fal.ai.
1. First, let me search for image generation models...
   [calls: fal-search-models with keyword "image generation"]

2. I'll use the flux-pro model. Let me get its schema...
   [calls: fal-get-model-schema with modelId "fal-ai/flux-pro"]

3. Now I'll generate the image...
   [calls: fal-enqueue with proper parameters]

4. Checking status...
   [calls: fal-get-status with requestId]

5. Retrieving the result...
   [calls: fal-get-result with requestId]

Example 2: List Available Models

User: What AI models are available on fal.ai?

Agent: Let me search for available models...
[calls: fal-list-models with limit 10]

Example 3: Get Model Details

User: Show me the input parameters for the flux-pro model

Agent: I'll fetch the schema for that model...
[calls: fal-get-model-schema with modelId "fal-ai/flux-pro"]

Available Tools

The MCP server exposes the following tools to AI agents:

🔍 Discovery Tools

`fal-list-models`

List all available models from fal.ai with optional pagination.

Parameters:

limit (number, optional): Maximum number of models to return
page (number, optional): Page number for pagination

Example:

{
    "limit": 20,
    "page": 1
}

`fal-search-models`

Search for models by keywords with optional category and limit filtering.

Parameters:

keyword (string, required): Search keyword (e.g., "image generation", "text to speech")
limit (number, optional): Maximum number of results
category (string, optional): Filter by category

Example:

{
    "keyword": "image generation",
    "limit": 10
}

`fal-get-model-schema`

Get the OpenAPI schema for a specific model to understand its input/output parameters.

Parameters:

modelId (string, required): Model identifier (e.g., "fal-ai/flux-pro")

Example:

{
    "modelId": "fal-ai/flux-pro"
}

⚡ Execution Tools

`fal-run-sync`

Run a model synchronously (blocks until completion). Best for fast models.

Parameters:

modelId (string, required): Model identifier
input (object, required): Model-specific input parameters

Example:

{
    "modelId": "fal-ai/flux-pro",
    "input": {
        "prompt": "A serene sunset over mountains",
        "image_size": "landscape_16_9"
    }
}

`fal-enqueue`

Queue a model execution asynchronously. Returns a request ID for status tracking.

Parameters:

modelId (string, required): Model identifier
input (object, required): Model-specific input parameters

Returns: { request_id: string }

📊 Status & Result Tools

`fal-get-status`

Check the status of an asynchronous job.

Parameters:

requestId (string, required): Request ID from fal-enqueue
modelId (string, required): Model identifier

Returns: Status object with state (IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED)

`fal-get-result`

Retrieve the result of a completed asynchronous job.

Parameters:

requestId (string, required): Request ID from fal-enqueue
modelId (string, required): Model identifier

Returns: Model output (automatically downloads and embeds images as base64)

🛑 Control Tools

`fal-cancel`

Cancel a running or queued asynchronous job.

Parameters:

requestId (string, required): Request ID from fal-enqueue
modelId (string, required): Model identifier

Available Resources

The MCP server provides the following resources:

`config://fal`

Configuration information about the current fal.ai connection.

`docs://fal/usage`

Usage guide showing the typical workflow for generating images and running models.

`docs://fal/tools-reference`

Quick reference documentation for all available tools.

`fal-model://{modelId}/schema`

Dynamic resource that returns the OpenAPI schema for any model.

Example: fal-model://fal-ai/flux-pro/schema

Available Prompts

`review-fal-prompt`

A prompt template that helps improve image generation prompts for better fal.ai results.

Parameters:

prompt (string): Your original image prompt

Usage: The agent can use this prompt to enhance your image generation requests.

Developer Examples

The package includes several example scripts for testing and development:

List Models Example

cd packages/mcp-fal-ai
npm run build
FAL_API_KEY=YOUR_KEY npm run example:list-models

This example demonstrates:

Listing available models with pagination
Searching for models by keyword
Displaying model information

Generate Image Example

FAL_API_KEY=YOUR_KEY npm run example:generate-nano-banana

This example shows:

Enqueueing an image generation job
Polling for job status with progress updates
Retrieving the final result

Get Model Schema Example

FAL_API_KEY=YOUR_KEY npm run example:get-model-schema

This example demonstrates:

Fetching model schemas
Understanding input/output parameters

Implementation Status

✅ Core Functionality Complete

✅ 8 MCP Tools (discovery, execution, status, control)
✅ 4 MCP Resources (config, documentation, model schemas)
✅ 1 MCP Prompt (prompt enhancement)
✅ Dual transport support (stdio & SSE)
✅ TypeScript with strict type safety
✅ Zod-based validation
✅ Custom error handling
✅ HTTP client (no SDK dependency)

🚧 Potential Future Enhancements

File upload tool (fal-upload-file)
Convenience tool with auto-polling (fal-enqueue-and-wait)
Rate limit handling with exponential backoff
Request logging with secret redaction
Comprehensive test suite

Project Structure

packages/mcp-fal-ai/
├── README.md                    # This file
├── package.json                 # NPM package configuration
├── tsconfig.json                # TypeScript configuration
├── src/
│   ├── index.ts                 # CLI entry point
│   ├── server/
│   │   └── index.ts             # MCP server (stdio/SSE)
│   ├── config/
│   │   └── env.ts               # Environment validation (Zod)
│   ├── services/
│   │   └── fal-client.ts        # HTTP client for fal.ai API
│   ├── tools/
│   │   └── index.ts             # MCP tool implementations
│   ├── resources/
│   │   └── index.ts             # MCP resource implementations
│   ├── prompts/
│   │   └── index.ts             # MCP prompt implementations
│   ├── types/
│   │   └── model.ts             # Type definitions
│   ├── errors/
│   │   ├── api-errors.ts        # HTTP error classes
│   │   └── environment-validation-error.ts
│   └── utils/                   # Utility functions
├── dist/                        # Compiled output (generated)
└── examples/                    # Example scripts

Architecture Overview

Execution Flow

AI Agent (Cursor, Claude, ChatGPT, etc.)
    ↓
MCP Server (stdio or SSE transport)
    ├─ 8 Tools (discovery, execution, status, control)
    ├─ 4 Resources (config, docs, schemas)
    └─ 1 Prompt (enhancement)
    ↓
FalClient (HTTP wrapper)
    ├─ Authentication (Key header)
    ├─ Request/Response handling
    └─ Error mapping
    ↓
fal.ai API
    ├─ https://fal.ai/api (models catalog)
    ├─ https://fal.run (sync execution)
    └─ https://queue.fal.run (async execution)

Execution Modes

Synchronous Mode (fal-run-sync)

Direct execution via https://fal.run
Blocks until model completes
Best for fast models (<30 seconds)
Returns result immediately

Asynchronous Mode (fal-enqueue → fal-get-status → fal-get-result)

Queue-based execution via https://queue.fal.run
Returns request ID immediately
Poll status until completion
Best for long-running models

Technical Details

Type Safety

✅ Strict TypeScript mode enabled (strict: true)
✅ No any types (use unknown when type is uncertain)
✅ Explicit type annotations on all functions
✅ Zod schemas for runtime validation
✅ One type per file convention

Error Handling

Custom error classes for different HTTP status codes:

401 → UnauthorizedError     // Invalid API key
403 → ForbiddenError         // Access denied
404 → NotFoundError          // Model/endpoint not found
429 → RateLimitError         // Too many requests
5xx → ServerError            // fal.ai server error
4xx → ApiError               // Other client errors

Environment Variables

Required:

FAL_API_KEY: Your fal.ai API key

Optional:

RUN_SSE: Enable SSE transport (default: false)
PORT: SSE server port (default: 3001)

Dependencies

Production

Package	Purpose
`@modelcontextprotocol/sdk`	MCP server/client SDK
`zod`	Runtime schema validation
`zod-to-json-schema`	Convert Zod to JSON Schema
`yargs`	CLI argument parsing
`undici`	Fast HTTP client
`express`	SSE server (when enabled)

Development

Package	Purpose
`typescript`	TypeScript compiler
`@types/node`	Node.js type definitions
`shx`	Cross-platform shell commands

Troubleshooting

MCP Server Not Connecting

Check API Key: Ensure FAL_API_KEY is set correctly
Restart Agent: Restart your AI agent after configuration changes
Check Logs: Look for error messages in your agent's console
Test Manually: Run FAL_API_KEY=xxx npx @monsoft/mcp-fal-ai to test

Tool Calls Failing

Invalid Model ID: Ensure model ID is correct (e.g., fal-ai/flux-pro)
Invalid Input: Check model schema with fal-get-model-schema
API Key Issues: Verify your API key has sufficient permissions
Rate Limits: You may be hitting fal.ai rate limits

Common Issues

Issue: Environment validation failed: FAL_API_KEY is required Solution: Set the FAL_API_KEY environment variable

Issue: UnauthorizedError when calling tools Solution: Your API key may be invalid or expired

Issue: Tools not appearing in agent Solution: Check MCP server configuration and restart agent

Contributing

Contributions are welcome! Please follow these guidelines:

Code Style: Follow TypeScript best practices (see typescript.rules)
MCP Patterns: Follow MCP conventions (see model-context-protocol.rules)
Type Safety: Use strict TypeScript, avoid any
Documentation: Add JSDoc comments to public APIs
Testing: Test changes with example scripts
Commits: Use clear, descriptive commit messages

Development Setup

git clone https://github.com/Monsoft-Solutions/model-context-protocols.git
cd model-context-protocols/packages/mcp-fal-ai
npm install
npm run build

Running Examples

FAL_API_KEY=xxx npm run example:list-models
FAL_API_KEY=xxx npm run example:generate-nano-banana
FAL_API_KEY=xxx npm run example:get-model-schema

Links & Resources

License

MIT License - see LICENSE file for details

Support

🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Contact: support@monsoftsolutions.com

Package Version: 0.1.0
Last Updated: October 17, 2025
Status: Production Ready ✅

Available Tools

8 tools

fal-cancelD

Cancel a the given request

ParametersJSON Schema

Name	Required	Description	Default
`requestId`	Yes
`modelId`	Yes

TDQS

D1.8/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It does not disclose what happens on cancel (e.g., side effects, if request can be canceled after completion, or permission requirements). The behavior is entirely opaque beyond the action name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very short but ungrammatical ('a the'). While brevity is valued, this description lacks clarity and proper structure, making it less effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, no annotations, and minimal parameter info, the description is severely incomplete. It does not explain return values, error states, or lifecycle implications of cancelation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 2 parameters (requestId, modelId) with 0% description coverage. The description adds no meaning for these parameters, failing to explain their roles or expected values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb 'cancel' and the resource 'request', which aligns with the tool name. However, the phrasing 'a the given request' is grammatically poor and vague, not specifying what type of request (e.g., queued inference). It distinguishes from siblings like fal-enqueue and fal-get-status by implying a cancellation action, but lacks precision.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Siblings include fal-enqueue (create), fal-get-status (check status), and fal-get-result (fetch results), but the description does not mention these or provide context for cancelation scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fal-enqueueC

Enqueue a model. The model is enqueued using the fal.run endpoint. You need to check the status of the model using the fal-get-status tool, then get the result using the fal-get-result tool.

ParametersJSON Schema

Name	Required	Description	Default
`modelId`	Yes
`input`	No

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully convey behavioral traits. It only implies asynchronous execution and mentions the endpoint, but lacks details on idempotency, errors, rate limits, or return value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences, front-loading the main action and providing essential workflow instructions without extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description should explain what the tool returns and fully cover the workflow. It partially does by mentioning status checking, but omits parameter details and does not clarify the return value or job identification.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description does not explain the two parameters ('modelId' and 'input'). The agent receives no guidance on what these parameters mean or how to use them, forcing reliance on the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Enqueue a model') and mentions the underlying endpoint. However, it does not explicitly contrast with the sibling tool 'fal-run-sync' which likely offers synchronous execution, so differentiation is implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a workflow hint by instructing to check status and get result afterward, but it does not specify when to use this tool versus alternatives like 'fal-run-sync' or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fal-get-model-schemaC

Get the schema for a model. The model schema is used to understand the input and output of the model. use the modelId to get the schema of the model.

ParametersJSON Schema

Name	Required	Description	Default
`modelId`	Yes

TDQS

C2.7/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description does not disclose read-only nature, side effects, authentication needs, or rate limits. The statement is purely functional without behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, but the second sentence is redundant (explains purpose of schema) and the third repeats the first. Could be two sentences without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and simple input, the description should at least hint at the structure of the returned schema or how to interpret it. It only says 'schema' but no details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% with no parameter descriptions; the description only repeats the parameter name 'modelId' and says 'use it to get the schema'. No additional meaning beyond the schema's type string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'schema for a model', which is distinct from sibling tools like fal-list-models. No confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like fal-list-models or fal-run-sync. No context about prerequisites or typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fal-get-resultA

Get the result of a model execution and automatically download any image URLs in the response. Returns the model output with embedded base64 image data for any image URLs found. You need to check the status of the model using the fal-get-status tool first.

ParametersJSON Schema

Name	Required	Description	Default
`requestId`	Yes
`modelId`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses automatic download and base64 embedding of image URLs, a key behavioral trait. No annotations provided, so description carries full burden; lacks error handling or rate limit info but sufficient for core behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no redundancy, front-loaded with primary action and secondary usage guideline.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Describes output (model output with embedded base64 images) but lacks full output schema. Adequate but could be improved with more details on return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Parameters (requestId, modelId) are not explained in description. With 0% schema description coverage, description should compensate but does not add meaning beyond tool purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it gets model execution results and automatically processes image URLs, distinguishing it from siblings like fal-get-status and fal-cancel.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to check status first via fal-get-status, providing a clear prerequisite. No explicit alternatives or when-not-to-use, but effectively guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fal-get-statusB

Get the status of a model. The status is returned using the fal.run endpoint. You need to check the status of the model using the fal-get-status tool, then get the result using the fal-get-result tool.

ParametersJSON Schema

Name	Required	Description	Default
`requestId`	Yes
`modelId`	Yes

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, and the description provides minimal behavioral detail (only that status is returned via fal.run endpoint). Does not disclose read-only nature, error handling, or response format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: one for purpose, one for workflow. Could be more structured but is efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 params, no output schema, and no annotations, the description provides the essential workflow link to fal-get-result but lacks details on status values, error conditions, or parameter origin.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the purpose or format of requestId and modelId beyond their names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool gets the status of a model and distinguishes it from fal-get-result by indicating the workflow order.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to use this tool before fal-get-result, providing a clear workflow. However, no mention of when not to use or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fal-list-modelsA

List all available models from fal.ai with optional pagination parameters. Avoid listing all models at once as it may be too many models to process.. Use the limit and page parameters to paginate the results.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`page`	No

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It warns about potential issues with too many models but does not disclose other behavioral traits such as whether the operation is read-only, rate limits, or side effects. The warning is useful but insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two concise sentences with no unnecessary information. The first sentence clearly states the purpose, and the second provides essential usage guidance. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with two parameters and no output schema, the description covers the basic purpose and pagination advice. However, it lacks details about default behavior, result format, or whether results are sorted, leaving some gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It mentions using limit and page for pagination but does not explain their semantics (e.g., maximum limit, zero-based indexing, defaults). This adds minimal value beyond the schema's parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all available models from fal.ai with optional pagination, using a specific verb (list) and resource (models). It distinguishes from sibling tools like fal-search-models, which implies search/filter functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises against listing all models at once and recommends using pagination parameters, providing clear when-to-use guidance. However, it does not mention alternatives or when to avoid this tool in favor of others like fal-search-models.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fal-run-syncA

Run a model synchronously and automatically download any image URLs in the response. The model is run synchronously using the fal.run endpoint. Returns the model output with embedded base64 image data for any image URLs found.

ParametersJSON Schema

Name	Required	Description	Default
`modelId`	Yes
`input`	No

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses synchronous execution, automatic image URL download, and base64 embedding. Missing details on failure handling or side effects, but provides key behavioral traits beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the primary action, each sentence contributes unique value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Missing parameter descriptions and usage context. Despite explaining the return format, the lack of parameter guidance makes it incomplete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% with no parameter descriptions. The tool description adds no meaning to modelId or input parameters, leaving the agent without guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs a model synchronously and automatically processes image URLs, distinguishing it from async alternatives like fal-enqueue.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs siblings like fal-enqueue or fal-get-result. The description does not mention when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fal-search-modelsC

Search for models by keywords with optional category and limit filtering. The keywords are used to search for models that match the keywords.

ParametersJSON Schema

Name	Required	Description	Default
`keyword`	Yes
`limit`	No
`category`	No

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description bears full responsibility for behavioral disclosure. It only describes a search (implied read operation) without mentioning any side effects, rate limits, or response characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, but the second sentence ('The keywords are used to search for models that match the keywords.') is redundant with the first and could be removed to improve conciseness. The structure is acceptable but not optimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks details about output format, default limit, valid category values, or pagination. Given no output schema, more context is needed for an agent to fully understand the tool's behavior and results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should compensate but only briefly mentions 'optional category and limit filtering' without explaining what values category accepts or what limit controls. The keyword parameter is obvious but not elaborated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Search for models') and mentions the filtering options ('keywords with optional category and limit filtering'), distinguishing it from sibling tools like fal-list-models. However, it could be more specific about what constitutes a model search versus listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool vs alternatives such as fal-list-models or fal-get-model-schema. The description does not include 'when to use' or 'when not to use' instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

8 tool updatesv1.0.0Apr 28, 2026
- First observedfal-cancel
- First observedfal-enqueue
- First observedfal-get-model-schema
- First observedfal-get-result
- First observedfal-get-status
- First observedfal-list-models
- First observedfal-run-sync
- First observedfal-search-models

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0

Disambiguation5/5

Each tool has a distinct purpose (cancel, enqueue, schema, result, status, list, run sync, search) with clear descriptions that differentiate async and sync operations.

Naming Consistency5/5

All tools follow a consistent 'fal-verb' pattern with hyphens, e.g., fal-list-models, fal-run-sync, making it predictable.

Tool Count5/5

8 tools is well-scoped for a model inference server, covering essential operations without unnecessary bloat or deficiency.

Completeness5/5

The tool surface covers the full lifecycle: discover models (list/search), get schema, run (sync/async), check status, get result, and cancel, leaving no obvious gaps.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcp-aichatOAuth
io.github.AceDataCloud
MCP server for AI dialogue using various LLM models via AceDataCloud
AI & Machine Learning
2
mcp-qwen-imageOAuth
io.github.AceDataCloud
MCP server for Qwen Image 3 AI image generation
AI & Machine Learning Image & Video Processing
1
mcp-flux-proOAuth
io.github.AceDataCloud
MCP server for Flux AI image generation
Image & Video Processing Multimedia Processing
23
Danushkumar-V-mcp-discordOAuth
ai.smithery
An MCP server that integrates with Discord to provide AI-powered features.
Communication Social Media App Automation
2

Related MCP Servers

FAL Image/Video MCP Server
Image & Video Processing Multimedia Processing
RamboRogers
A
license
C
quality
D
maintenance
High-performance MCP server that enables generation of images and videos using FAL AI models with automatic downloads to your local machine.
Updated a year ago (2025-06-12 01:32 UTC)
24
36
8
MIT
fal-mcp
Image & Video Processing Multimedia Processing App Automation
guillaumeboniface
F
license
A
quality
D
maintenance
An MCP server that integrates fal.ai's image generation and editing capabilities into MCP-compatible clients. It enables text-to-image generation, style application via LoRAs, and image editing using natural language instructions.
Updated 7 months ago (2026-02-20 03:53 UTC)
6
-
mcp-fal
AI & Machine Learning Image & Video Processing
MohsenMousaviEyeline
F
license
A
quality
D
maintenance
An MCP server that exposes Fal.ai generative media models as tools for image and video generation, and running any Fal.ai model, callable by Claude and other MCP-compatible clients.
Updated 3 months ago (2026-06-01 15:20 UTC)
3
-
fal-ai-mcp-server
Image & Video Processing AI & Machine Learning
piebro
A
license
Not graded
quality
D
maintenance
An MCP server to use the fal.ai APIs to generate images and videos.
Updated a year ago (2025-04-27 17:42 UTC)
4
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Forge-Systems-Hub/mcp-fal-ai-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server