FAL Image/Video MCP Server

Instructions

Implementation Reference

• src/index.ts:495-563 (handler)

  Main handler function that executes the ideogram_v3 tool by calling the FAL API endpoint, handling model-specific parameters like negative_prompt, and processing the generated images with download and data URL support.

  private async handleImageGeneration(args: any, model: any) {
    const {
      prompt,
      image_size = 'landscape_4_3',
      num_inference_steps = 25,
      guidance_scale = 3.5,
      num_images = 1,
      negative_prompt,
      safety_tolerance,
      raw,
    } = args;
  
    try {
      // Configure FAL client lazily with query config override
      configureFalClient(this.currentQueryConfig);
      const inputParams: any = { prompt };
      
      // Add common parameters
      if (image_size) inputParams.image_size = image_size;
      if (num_images > 1) inputParams.num_images = num_images;
      
      // Add model-specific parameters based on model capabilities
      if (model.id.includes('flux') || model.id.includes('stable_diffusion')) {
        if (num_inference_steps) inputParams.num_inference_steps = num_inference_steps;
        if (guidance_scale) inputParams.guidance_scale = guidance_scale;
      }
      if ((model.id.includes('stable_diffusion') || model.id === 'ideogram_v3') && negative_prompt) {
        inputParams.negative_prompt = negative_prompt;
      }
      if (model.id.includes('flux_pro') && safety_tolerance) {
        inputParams.safety_tolerance = safety_tolerance;
      }
      if (model.id === 'flux_pro_ultra' && raw !== undefined) {
        inputParams.raw = raw;
      }
  
      const result = await fal.subscribe(model.endpoint, { input: inputParams });
      const imageData = result.data as FalImageResult;
  
      const processedImages = await downloadAndProcessImages(imageData.images, model.id);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              model: model.name,
              id: model.id,
              endpoint: model.endpoint,
              prompt,
              images: processedImages,
              metadata: inputParams,
              download_path: DOWNLOAD_PATH,
              data_url_settings: {
                enabled: ENABLE_DATA_URLS,
                max_size_mb: Math.round(MAX_DATA_URL_SIZE / 1024 / 1024),
              },
              autoopen_settings: {
                enabled: AUTOOPEN,
                note: AUTOOPEN ? "Files automatically opened with default application" : "Auto-open disabled"
              },
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new Error(`${model.name} generation failed: ${error}`);
    }
  }

• src/index.ts:103-103 (registration)

  Model registry definition that registers the ideogram_v3 tool with its FAL endpoint and metadata. This is used to dynamically generate tool schemas and dispatch to the correct handler.

  { id: 'ideogram_v3', endpoint: 'fal-ai/ideogram/v3', name: 'Ideogram V3', description: 'Advanced typography and realistic outputs' },

• src/index.ts:370-372 (schema)

  Specific schema extension in generateToolSchema that adds the negative_prompt input parameter to the tool schema for ideogram_v3.

  if (model.id.includes('stable_diffusion') || model.id === 'ideogram_v3') {
    baseSchema.inputSchema.properties.negative_prompt = { type: 'string', description: 'Negative prompt' };
  }

• src/index.ts:521-523 (handler)

  Model-specific logic in the handler to include negative_prompt in the API call parameters for ideogram_v3.

  if ((model.id.includes('stable_diffusion') || model.id === 'ideogram_v3') && negative_prompt) {
    inputParams.negative_prompt = negative_prompt;
  }

• src/index.ts:531-535 (helper)

  Core API invocation using fal.subscribe to the ideogram_v3 endpoint and subsequent image processing helper call.

  const result = await fal.subscribe(model.endpoint, { input: inputParams });
  const imageData = result.data as FalImageResult;
  
  const processedImages = await downloadAndProcessImages(imageData.images, model.id);