Instantly MCP Server

Instructions

Implementation Reference

• src/handlers/lead-handler.ts:255-297 (handler)

  Core handler function executing the update_lead tool: validates lead_id, builds PATCH payload from args, calls Instantly API /leads/{lead_id}, formats MCP response.

  async function handleUpdateLead(args: any, apiKey: string) {
    console.error('[Instantly MCP] ✏️ Executing update_lead...');
  
    if (!args.lead_id) {
      throw new McpError(ErrorCode.InvalidParams, 'Lead ID is required for update_lead');
    }
  
    // Build update data with all supported parameters from Instantly.ai API v2
    const updateData: any = {};
  
    // Core lead information
    if (args.personalization !== undefined) updateData.personalization = args.personalization;
    if (args.website !== undefined) updateData.website = args.website;
    if (args.last_name !== undefined) updateData.last_name = args.last_name;
    if (args.first_name !== undefined) updateData.first_name = args.first_name;
    if (args.company_name !== undefined) updateData.company_name = args.company_name;
    if (args.phone !== undefined) updateData.phone = args.phone;
  
    // Advanced parameters
    if (args.lt_interest_status !== undefined) updateData.lt_interest_status = args.lt_interest_status;
    if (args.pl_value_lead !== undefined) updateData.pl_value_lead = args.pl_value_lead;
    if (args.assigned_to !== undefined) updateData.assigned_to = args.assigned_to;
  
    // Custom variables
    if (args.custom_variables !== undefined) updateData.custom_variables = args.custom_variables;
  
    console.error(`[Instantly MCP] 📤 Updating lead ${args.lead_id} with data: ${JSON.stringify(updateData, null, 2)}`);
  
    const updateResult = await makeInstantlyRequest(`/leads/${args.lead_id}`, { method: 'PATCH', body: updateData }, apiKey);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            lead: updateResult,
            message: 'Lead updated successfully'
          }, null, 2)
        }
      ]
    };
  }

• src/tools/lead-tools.ts:77-99 (registration)

  MCP tool registration in leadTools array: defines name, title, description, inputSchema for update_lead.

  {
    name: 'update_lead',
    title: 'Update Lead',
    description: 'Update lead (partial). ⚠️ custom_variables replaces entire object.',
    annotations: { destructiveHint: false },
    inputSchema: {
      type: 'object',
      properties: {
        lead_id: { type: 'string', description: 'Lead UUID' },
        personalization: { type: 'string' },
        website: { type: 'string' },
        last_name: { type: 'string' },
        first_name: { type: 'string' },
        company_name: { type: 'string' },
        phone: { type: 'string' },
        lt_interest_status: { type: 'number' },
        pl_value_lead: { type: 'string' },
        assigned_to: { type: 'string' },
        custom_variables: { type: 'object', description: 'Replaces all - include existing!' }
      },
      required: ['lead_id']
    }
  },

• src/validation.ts:489-501 (schema)

  Zod schema (UpdateLeadSchema) for input validation of update_lead tool parameters, used by validateUpdateLeadData.

  export const UpdateLeadSchema = z.object({
    lead_id: z.string().min(1, { message: 'Lead ID cannot be empty' }),
    personalization: z.string().optional(),
    website: z.string().url().optional(),
    last_name: z.string().optional(),
    first_name: z.string().optional(),
    company_name: z.string().optional(),
    phone: z.string().optional(),
    lt_interest_status: z.number().int().min(-3).max(4).optional(),
    pl_value_lead: z.string().optional(),
    assigned_to: z.string().optional(),
    custom_variables: z.record(z.string(), z.any()).optional()
  });