Fal.ai MCP Server

Instructions

Implementation Reference

• src/fal_mcp_server/handlers/utility_handlers.py:18-95 (handler)

  Core implementation of the list_models tool handler. Retrieves models from the registry based on task, category, search, and limit parameters, handles fallback logic, and formats results as a markdown list with badges for featured models.
  async def handle_list_models( arguments: Dict[str, Any], registry: ModelRegistry, ) -> List[TextContent]: """Handle the list_models tool.""" task = arguments.get("task") category = arguments.get("category") search = arguments.get("search") limit = arguments.get("limit", 20) used_fallback = False fallback_warning = "" # If task is provided, use semantic search with API if task: # Map simplified category to API category for search api_category = None if category: category_map = { "image": "text-to-image", "video": "text-to-video", "audio": "text-to-audio", } api_category = category_map.get(category) search_result = await registry.search_models( query=task, category=api_category, limit=limit ) models = search_result.models used_fallback = search_result.used_fallback if used_fallback: title = f'## Models for: "{task}" ({len(models)} found)\n' fallback_warning = f"⚠️ *Using cached results ({search_result.fallback_reason}). Results may be less relevant.*\n" subtitle = "💡 *⭐ = Featured by Fal.ai*\n" else: title = f'## Models for: "{task}" ({len(models)} found)\n' subtitle = "💡 *Sorted by relevance. ⭐ = Featured by Fal.ai*\n" else: # Standard list with optional search filter models = await registry.list_models( category=category, search=search, limit=limit ) title = f"## Available Models ({len(models)} found)\n" subtitle = "" if not models: return [ TextContent( type="text", text="No models found. Try a different category, task, or search term.", ) ] # Format output lines = [title] if fallback_warning: lines.append(fallback_warning) if subtitle: lines.append(subtitle) for model in models: # Add star badge for highlighted models highlighted_badge = " ⭐" if model.highlighted else "" lines.append(f"- `{model.id}`{highlighted_badge}") if model.name and model.name != model.id: lines.append(f" - **{model.name}**") if model.description: desc = ( model.description[:150] + "..." if len(model.description) > 150 else model.description ) lines.append(f" - {desc}") if task and model.group_label: lines.append(f" - *Family: {model.group_label}*") return [TextContent(type="text", text="\n".join(lines))]
• src/fal_mcp_server/tools/utility_tools.py:12-41 (schema)

  Input schema definition for the list_models tool, including optional parameters for category, task (semantic), search, and limit.
  Tool( name="list_models", description="Discover available Fal.ai models for image, video, and audio generation. Use 'task' parameter for intelligent task-based ranking (e.g., 'portrait photography'), or 'search' for simple name/description filtering.", inputSchema={ "type": "object", "properties": { "category": { "type": "string", "enum": ["image", "video", "audio"], "description": "Filter by category (image, video, or audio)", }, "task": { "type": "string", "description": "Task description for intelligent ranking (e.g., 'anime illustration', 'product photography'). Uses Fal.ai's semantic search and prioritizes featured models.", }, "search": { "type": "string", "description": "Simple search query to filter models by name or description (e.g., 'flux'). Use 'task' for better semantic matching.", }, "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100, "description": "Maximum number of models to return", }, }, "required": [], }, ),
• src/fal_mcp_server/server.py:61-85 (registration)

  Registration of the list_models handler in the TOOL_HANDLERS dictionary used by the call_tool MCP server method to route tool calls to their implementations.
  TOOL_HANDLERS = { # Utility tools (no queue needed) "list_models": handle_list_models, "recommend_model": handle_recommend_model, "get_pricing": handle_get_pricing, "get_usage": handle_get_usage, "upload_file": handle_upload_file, # Image generation tools "generate_image": handle_generate_image, "generate_image_structured": handle_generate_image_structured, "generate_image_from_image": handle_generate_image_from_image, # Image editing tools "remove_background": handle_remove_background, "upscale_image": handle_upscale_image, "edit_image": handle_edit_image, "inpaint_image": handle_inpaint_image, "resize_image": handle_resize_image, "compose_images": handle_compose_images, # Video tools "generate_video": handle_generate_video, "generate_video_from_image": handle_generate_video_from_image, "generate_video_from_video": handle_generate_video_from_video, # Audio tools "generate_music": handle_generate_music, }
• src/fal_mcp_server/tools/__init__.py:14-16 (registration)

  Aggregation of all tool schemas (including list_models from UTILITY_TOOLS) into ALL_TOOLS list returned by the list_tools MCP server method.
  ALL_TOOLS = ( UTILITY_TOOLS + IMAGE_TOOLS + IMAGE_EDITING_TOOLS + VIDEO_TOOLS + AUDIO_TOOLS )
• src/fal_mcp_server/handlers/__init__.py:23-29 (helper)

  Import and exposure of the handle_list_models function in handlers package __init__.py for use by server modules.
  from fal_mcp_server.handlers.utility_handlers import ( handle_get_pricing, handle_get_usage, handle_list_models, handle_recommend_model, handle_upload_file, )