Fal.ai MCP Server
A Model Context Protocol (MCP) server for discovering and documenting Fal.ai models. This server provides tools for coding agents to learn about available models, their schemas, capabilities, and usage patterns.
Features
- Model Discovery: List and search Fal.ai models with comprehensive filtering and sorting
- Model Information: Get detailed metadata about specific models, including pricing (with API key)
- Schema Retrieval: Fetch OpenAPI schemas for model parameters
- Documentation: Generate comprehensive documentation with usage examples
- Caching: Cloudflare KV-based caching for fast model lookups
- Optional Authentication: Works without API keys, with optional auth for higher rate limits and pricing access
- Advanced Filtering: Filter by category, status, tags, owner, highlighted, pinned, kind, and more
- Flexible Sorting: Sort by update date, name, category, or owner
Available Tools
list_models
List all available Fal.ai models for image, video, and audio generation with comprehensive filtering and sorting options.
Use this tool when:
- User asks about available models
- User wants to discover models by category, status, tags, or owner
- User needs to find specific model types (e.g., "show me new image models")
- User asks "what models are available?" or "show me image models"
- Coding agent needs to discover what models exist
- User wants to filter by tags like "new", "beta", "pro", "turbo"
- User wants to find models from a specific owner/organization
Filtering Options:
- category: Filter by API category from metadata.category (e.g., "text-to-image", "image-to-video") or array of categories - models must match ANY specified category (e.g., ["text-to-image", "image-to-video"])
- status: Filter by status (active, deprecated)
- tags: Filter by tags - models must have ALL specified tags (e.g., ["new", "beta"])
- owner: Filter by model owner/organization (e.g., "fal-ai", "clarityai")
- highlighted: Filter to only highlighted models
- pinned: Filter to only pinned models
- kind: Filter by model kind (inference, training)
- search: Free-text search across name, description, ID, and tags
Common API Categories: "text-to-image", "image-to-image", "text-to-video", "image-to-video", "video-to-video", "image-to-3d", "text-to-audio", "audio", "audio-to-audio", "speech-to-text", "text-to-speech", "training"
Sorting Options:
- updated_at: Most recently updated models first (default for discovery)
- name: Alphabetical by name
- category: Grouped by category, then alphabetical
- owner: Grouped by owner, then alphabetical
Parameters:
- category (optional): Filter by API category (e.g., "text-to-image", "image-to-video") or array of categories - models must match ANY specified category
- status (optional): Filter by status (active, deprecated)
- tags (optional): Filter by tags array - models must have ALL specified tags
- owner (optional): Filter by model owner/organization
- highlighted (optional): Filter to only highlighted models (boolean)
- pinned (optional): Filter to only pinned models (boolean)
- kind (optional): Filter by model kind (inference, training)
- search (optional): Free-text search across name, description, ID, and tags
- limit (optional): Maximum number of results (1-100, default: 20)
- sortBy (optional): Sort field - "updated_at", "name", "category", or "owner"
Examples:
// Basic search
{
"category": "text-to-image",
"search": "flux",
"limit": 10
}
// Advanced filtering
{
"category": ["text-to-image", "image-to-image"],
"status": "active",
"tags": ["new"],
"sortBy": "updated_at",
"limit": 20
}
get_model_info
Get detailed information about a specific Fal.ai model including metadata, capabilities, description, and pricing (when API key is provided).
Use this tool when:
- User asks about a specific model
- User wants to know what a model does
- User asks about model pricing or cost
- User needs model metadata
- Coding agent needs model details for integration
Returns comprehensive model information including ID, name, description, category, owner, capabilities, and pricing (when API key is provided via Authorization header).
Parameters:
- model_id (required): Model endpoint ID (e.g., "fal-ai/flux-pro") or alias (e.g., "flux_pro")
Example:
{
"model_id": "fal-ai/flux-pro"
}
get_model_schema
Get the OpenAPI/JSON schema for a Fal.ai model's input and output parameters.
Use this tool when:
- User needs to know what parameters a model accepts
- User asks about model API structure
- User wants to integrate a model programmatically
- Coding agent needs to understand model interface
- Developer needs request/response schema
Returns the complete schema including required/optional parameters, types, examples, and validation rules.
Parameters:
- model_id (required): Model endpoint ID or alias
Example:
{
"model_id": "fal-ai/flux/dev"
}
get_model_documentation
Get comprehensive documentation for a Fal.ai model including usage examples, best practices, parameter descriptions, and integration guides.
Use this tool when:
- User wants full documentation for a model
- User needs usage examples
- User asks "how do I use this model?"
- Coding agent needs complete model reference
- Developer needs integration guide
Returns markdown-formatted documentation with examples, parameter details, and best practices.
Parameters:
- model_id (required): Model endpoint ID or alias
Example:
{
"model_id": "fal-ai/flux-pro"
}
MCP Client Configuration
API Key Configuration (Optional)
API keys are optional but recommended to avoid rate limits. The server works without authentication, but authenticated requests have higher rate limits.
How It Works
The server extracts API keys from the Authorization header in MCP client requests:
Authorization: Key <your-fal-api-key>
Configuring MCP Clients
Claude Desktop
Add custom headers in your Claude Desktop configuration:
{
"mcpServers": {
"fal-ai": {
"command": "npx",
"args": [
"mcp-remote",
"https://fal-mcp.your-account.workers.dev/mcp"
],
"env": {
"FAL_API_KEY": "your-fal-api-key-here"
}
}
}
}
Note: The exact method for passing headers depends on your MCP client. Some clients may require using a proxy or wrapper to inject headers.
Other MCP Clients
Check your MCP client's documentation for how to pass custom headers. The server expects:
- Header name: Authorization
- Header value: Key <your-api-key>
Getting a Fal.ai API Key
- Sign up at fal.ai
- Navigate to your account settings
- Generate an API key
- Use it in the Authorization header format: Key <your-api-key>
Connecting to MCP Clients
Using mcp-remote
For local MCP clients like Claude Desktop, use the mcp-remote package:
npm install -g mcp-remote
Then configure your MCP client to use:
npx mcp-remote https://fal-mcp.your-account.workers.dev/mcp
Direct Connection
If your MCP client supports streamable HTTP transport, connect directly to:
https://fal-mcp.your-account.workers.dev/mcp
Architecture
Components
- MCP Server (src/index.ts): Main entry point, handles HTTP requests and routes to MCP agent
- Model Registry (src/registry/model-registry.ts): Manages model cache with KV storage and alias resolution
- API Client (src/utils/fal-api.ts): Handles all Fal.ai Platform API calls
- Tools (src/tools/fal-ai.tools.ts): MCP tool implementations
- Types (src/types/fal-model.ts): TypeScript interfaces and Zod schemas
Caching Strategy
- Models are cached in Cloudflare KV with a 1-hour TTL
- Cache is automatically refreshed when expired
- Falls back to stale cache if API calls fail
- Supports graceful degradation without API keys
API Integration
The server uses the Fal.ai Platform API for:
- Model discovery with pagination (GET /v1/models)
- Model metadata retrieval
- OpenAPI schema expansion (expand=openapi-3.0)
- Pricing information (GET /v1/models/pricing) - requires authentication
All API calls are made server-side, so MCP clients don't need direct API access.
References