FAL Image/Video MCP Server

Instructions

Implementation Reference

• src/index.ts:719-798 (handler)

  Core handler function that executes custom FAL models via fal.subscribe(endpoint, input_params), processes outputs (images/videos) with download/dataUrl handling based on category_hint, returns structured JSON response.
  private async handleCustomModel(args: any) { const { endpoint, input_params, category_hint = 'other' } = args; try { // Configure FAL client lazily with query config override configureFalClient(this.currentQueryConfig); const result = await fal.subscribe(endpoint, { input: input_params }); // Handle different output types based on category hint if (category_hint === 'image' || category_hint === 'other') { // Assume image output const data = result.data as any; if (data.images && Array.isArray(data.images)) { const processedImages = await downloadAndProcessImages(data.images, endpoint.replace(/[^a-zA-Z0-9]/g, '_')); return { content: [ { type: 'text', text: JSON.stringify({ endpoint, category_hint, images: processedImages, raw_output: data, input_params, download_path: DOWNLOAD_PATH, }, null, 2), }, ], }; } } else if (category_hint === 'video' || category_hint === 'image_to_video') { // Assume video output const data = result.data as any; if (data.video) { const videoProcessed = await downloadAndProcessVideo(data.video.url, endpoint.replace(/[^a-zA-Z0-9]/g, '_')); return { content: [ { type: 'text', text: JSON.stringify({ endpoint, category_hint, video: { url: data.video.url, dataUrl: videoProcessed.dataUrl, localPath: videoProcessed.localPath, width: data.video.width, height: data.video.height, }, raw_output: data, input_params, download_path: DOWNLOAD_PATH, }, null, 2), }, ], }; } } // Fallback: return raw output return { content: [ { type: 'text', text: JSON.stringify({ endpoint, category_hint, raw_output: result.data, input_params, note: "Raw output - model type not recognized for enhanced processing" }, null, 2), }, ], }; } catch (error) { throw new Error(`Custom model execution failed for ${endpoint}: ${error}`); } }
• src/index.ts:428-451 (registration)

  Registers the 'execute_custom_model' tool in the MCP tools list response, defining its name, description, and input schema for dynamic tool listing.
  tools.push({ name: 'execute_custom_model', description: 'Execute any FAL model by specifying the endpoint directly', inputSchema: { type: 'object', properties: { endpoint: { type: 'string', description: 'FAL model endpoint (e.g., fal-ai/flux/schnell, fal-ai/custom-model)' }, input_params: { type: 'object', description: 'Input parameters for the model (varies by model)' }, category_hint: { type: 'string', enum: ['image', 'video', 'image_to_video', 'other'], default: 'other', description: 'Hint about the expected output type for proper handling' } }, required: ['endpoint', 'input_params'] } });
• src/index.ts:463-465 (handler)

  Dispatch point in the main CallToolRequest handler that routes 'execute_custom_model' calls to the handleCustomModel function.
  } else if (name === 'execute_custom_model') { return await this.handleCustomModel(args); }
• src/index.ts:1012-1035 (registration)

  Duplicate registration of the tool schema in the direct HTTP MCP message handler for tools/list.
  tools.push({ name: 'execute_custom_model', description: 'Execute any FAL model by specifying the endpoint directly', inputSchema: { type: 'object', properties: { endpoint: { type: 'string', description: 'FAL model endpoint (e.g., fal-ai/flux/schnell, fal-ai/custom-model)' }, input_params: { type: 'object', description: 'Input parameters for the model (varies by model)' }, category_hint: { type: 'string', enum: ['image', 'video', 'image_to_video', 'other'], default: 'other', description: 'Hint about the expected output type for proper handling' } }, required: ['endpoint', 'input_params'] } });
• src/index.ts:1053-1055 (handler)

  Dispatch point in the HTTP direct tool call handler routing to handleCustomModel.
  } else if (name === 'execute_custom_model') { toolResult = await this.handleCustomModel(args); } else {