Instantly MCP Server

Instructions

Implementation Reference

• src/instantly_mcp/tools/leads.py:162-201 (handler)

  The primary handler function that executes the update_lead tool. It constructs a partial update body from input parameters and sends a PATCH request to the /leads/{lead_id} endpoint, returning the JSON response.

  async def update_lead(params: UpdateLeadInput) -> str:
      """
      Update lead (partial update).
      
      ⚠️ IMPORTANT: custom_variables REPLACES the entire object!
      To preserve existing custom variables:
      1. First call get_lead to retrieve current values
      2. Merge your changes with existing values
      3. Pass the complete merged object
      
      Example: If lead has {"industry": "Tech"} and you want to add {"size": "Large"},
      you must pass {"industry": "Tech", "size": "Large"} - not just {"size": "Large"}
      """
      client = get_client()
      
      body: dict[str, Any] = {}
      
      if params.personalization is not None:
          body["personalization"] = params.personalization
      if params.website is not None:
          body["website"] = params.website
      if params.last_name is not None:
          body["last_name"] = params.last_name
      if params.first_name is not None:
          body["first_name"] = params.first_name
      if params.company_name is not None:
          body["company_name"] = params.company_name
      if params.phone is not None:
          body["phone"] = params.phone
      if params.lt_interest_status is not None:
          body["lt_interest_status"] = params.lt_interest_status
      if params.pl_value_lead is not None:
          body["pl_value_lead"] = params.pl_value_lead
      if params.assigned_to is not None:
          body["assigned_to"] = params.assigned_to
      if params.custom_variables is not None:
          body["custom_variables"] = params.custom_variables
      
      result = await client.patch(f"/leads/{params.lead_id}", json=body)
      return json.dumps(result, indent=2)

• src/instantly_mcp/models/leads.py:77-99 (schema)

  Pydantic BaseModel defining the input schema for the update_lead tool, including lead_id (required) and optional fields for partial updates.

  class UpdateLeadInput(BaseModel):
      """
      Input for updating a lead (partial update).
      
      ⚠️ custom_variables replaces entire object - include existing values!
      """
      
      model_config = ConfigDict(str_strip_whitespace=True, extra="ignore")
      
      lead_id: str = Field(..., description="Lead UUID")
      personalization: Optional[str] = Field(default=None)
      website: Optional[str] = Field(default=None)
      last_name: Optional[str] = Field(default=None)
      first_name: Optional[str] = Field(default=None)
      company_name: Optional[str] = Field(default=None)
      phone: Optional[str] = Field(default=None)
      lt_interest_status: Optional[int] = Field(default=None)
      pl_value_lead: Optional[str] = Field(default=None)
      assigned_to: Optional[str] = Field(default=None)
      custom_variables: Optional[dict[str, Any]] = Field(
          default=None,
          description="⚠️ REPLACES ALL - include existing values!"
      )

• src/instantly_mcp/tools/leads.py:450-463 (registration)

  The LEAD_TOOLS list exports the update_lead function along with other lead tools, which is used by get_all_tools() to collect and register tools with the MCP server.

  LEAD_TOOLS = [
      list_leads,
      get_lead,
      create_lead,
      update_lead,
      list_lead_lists,
      create_lead_list,
      update_lead_list,
      get_verification_stats_for_lead_list,
      add_leads_to_campaign_or_list_bulk,
      delete_lead,
      delete_lead_list,
      move_leads_to_campaign_or_list,
  ]

• src/instantly_mcp/server.py:89-90 (registration)

  TOOL_ANNOTATIONS dictionary entry for update_lead, specifying destructiveHint=False, applied during dynamic tool registration in register_tools().

  "create_lead": {"destructiveHint": False},
  "update_lead": {"destructiveHint": False},