@Monsoft/ Fal Ai

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)

---

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:

1. Visit fal.ai dashboard
2. Sign up or log in with your account
3. Navigate to API Keys section
4. Create a new API key
5. 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

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to Features → Model Context Protocol
3. Click Add MCP Server or edit your MCP configuration file
4. 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"
            }
        }
    }
}

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

🤖 Claude Desktop

1. 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

2. 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"
            }
        }
    }
}

3. Save the file and restart Claude Desktop
4. 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):

1. Access your MCP configuration settings
2. 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

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

Tool Calls Failing

1. Invalid Model ID: Ensure model ID is correct (e.g., fal-ai/flux-pro)
2. Invalid Input: Check model schema with fal-get-model-schema
3. API Key Issues: Verify your API key has sufficient permissions
4. 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:

1. Code Style: Follow TypeScript best practices (see typescript.rules)
2. MCP Patterns: Follow MCP conventions (see model-context-protocol.rules)
3. Type Safety: Use strict TypeScript, avoid any
4. Documentation: Add JSDoc comments to public APIs
5. Testing: Test changes with example scripts
6. 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

• 📦 NPM Package
• 🐙 GitHub Repository
• 🔧 fal.ai Documentation
• 🎨 fal.ai Model Catalog
• 📖 MCP Specification
• 🔑 fal.ai Dashboard

---

License

MIT License - see LICENSE file for details

---

Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Contact: [email protected]

---

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